HTML Dev Docs

Pure HTML5 Developer Documentation Portal

A professional, portfolio-worthy developer documentation portal built entirely with HTML5 — no CSS, no JavaScript, no frameworks, no build tools.

Live Demo · Features · Installation · Contributing

---

Project Description

HTML Dev Docs is a complete developer documentation website that demonstrates mastery of semantic HTML5 markup. Every page is valid HTML5, fully interconnected, and production-ready for deployment to GitHub Pages or any static file host.

This project intentionally uses only plain HTML to prove that well-structured semantic markup can power a realistic, multi-section documentation portal — complete with navigation, breadcrumbs, tables of contents, forms, media, and accessibility features.

Features

• 66 interconnected HTML pages across 8 documentation sections
• Pure HTML5 — zero CSS, JavaScript, or external libraries in the site
• Semantic structure — header, nav, main, section, article, aside, footer
• Full element coverage — forms, tables, media, interactive elements, and more
• Accessibility — ARIA attributes, skip links, landmarks, and proper heading hierarchy
• GitHub Pages ready — automatic deployment via GitHub Actions
• MIT Licensed — free to use, fork, and customize

Screenshots

Social preview and project banner

Open index.html in any browser to explore the unstyled, semantic documentation portal.

Live Demo

Once deployed to GitHub Pages, the site will be available at:

https://<your-username>.github.io/HTML-Dev-Docs/

Deploy to GitHub Pages

You must enable Pages manually once. The workflow cannot do this for you — GitHub blocks the default GITHUB_TOKEN from creating a Pages site.

1. Fork or clone this repository
2. Push to the main branch
3. Enable GitHub Pages (required before first deploy):
   • Open https://github.com/YOUR-USERNAME/HTML-Dev-Docs/settings/pages
   • Under Build and deployment, set Source to GitHub Actions
   • Do not choose "Deploy from a branch"
   • Save — no workflow file selection is needed
4. Go to Actions → Deploy to GitHub Pages → Re-run all jobs
5. After the first successful run, every push to main deploys automatically

Troubleshooting

Error	Cause	Fix
Get Pages site failed / Not Found	Pages not enabled	Complete step 3 above, then re-run
Resource not accessible by integration	Workflow tried to auto-enable Pages	Remove enablement: true; enable Pages manually in Settings
Node 20 deprecation warning	Old action version	This repo uses configure-pages@v6 and deploy-pages@v5 (Node 24)

enablement: true does not work with the default Actions token. It requires a Personal Access Token with administration:write — manual setup in Settings is simpler and recommended.

Installation

# Clone the repository
git clone https://github.com/<your-username>/HTML-Dev-Docs.git

# Navigate to the project
cd HTML-Dev-Docs

# Open in your browser (no build step required)
# Windows
start index.html

# macOS
open index.html

# Linux
xdg-open index.html

Optional: Local Server

For iframe and media testing, serve with any static file server:

# Python 3
python -m http.server 8080

# Then visit http://localhost:8080

Usage

1. Start at index.html — the portal homepage
2. Use the main navigation to browse sections
3. Follow breadcrumbs to understand page hierarchy
4. Use the table of contents in the sidebar for in-page navigation
5. Validate any page with the W3C Nu Html Checker

Documentation Sections

Section	Pages	Description
Getting Started	6	Introduction, installation, quick start
HTML Reference	10	Element-by-element HTML5 reference
Guides	10	Best practices and how-to guides
API Reference	10	REST API documentation examples
Tutorials	10	Step-by-step HTML5 tutorials
Examples	10	Real-world page pattern examples
Resources	5	Glossary, FAQ, cheatsheet, search
About	4	Team, contributing, contact, license

Project Structure

/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Pages CI/CD
├── assets/
│   ├── icon.svg                # Project logo (128×128)
│   ├── favicon.svg             # Browser favicon (32×32)
│   └── preview.png             # README / social preview
├── pages/
│   ├── getting-started/        # 6 pages
│   ├── html-reference/         # 10 pages
│   ├── guides/                 # 10 pages
│   ├── api/                    # 10 pages
│   ├── tutorials/              # 10 pages
│   ├── examples/               # 10 pages
│   ├── resources/              # 5 pages
│   └── about/                  # 4 pages
├── index.html                  # Homepage
├── robots.txt                  # Search engine & bot crawler rules
├── sitemap.xml                 # XML sitemap for all 66 pages
├── README.md                   # This file
├── LICENSE                     # MIT License
└── .gitignore

HTML Features Demonstrated

Every important HTML5 element appears in realistic documentation contexts:

Category	Elements
Structure	header, nav, main, section, article, aside, footer
Text	h1–h4, p, strong, em, mark, abbr, cite, q, blockquote
Lists	ul, ol, li, dl, dt, dd
Tables	table, caption, thead, tbody, tfoot, tr, th, td
Forms	form, fieldset, legend, label, input, select, textarea, button
Media	img, figure, figcaption, audio, video, iframe
Interactive	details, summary, progress, meter
Code	pre, code, kbd, samp, var
Metadata	meta, link, title, time, address
Navigation	Internal links, breadcrumbs, table of contents, skip links

Accessibility Features

• Skip to main content link on every page
• aria-label on navigation landmarks
• aria-labelledby connecting sections to headings
• aria-current="page" on active navigation items
• scope attributes on table headers
• alt text on all images
• label elements associated with form controls
• Semantic heading hierarchy (h1 → h4)
• role="banner" on site header
• role="search" on search form
• role="note" for supplementary content

SEO & Crawlers

• robots.txt — Crawler rules for search engines and bots (Googlebot, Bingbot, GPTBot, etc.)
• sitemap.xml — Complete XML sitemap listing all 66 pages for search indexing
• <link rel="sitemap"> — Sitemap reference in every page <head>
• #main-content anchors — Navigation links scroll directly to page content, not the topic list

Update SITE_BASE_URL in sitemap.xml and robots.txt to match your GitHub Pages URL before deploying.

Browser Support

Browser	Support
Chrome	✅ Full
Firefox	✅ Full
Safari	✅ Full
Edge	✅ Full
Opera	✅ Full

All modern browsers support HTML5 semantic elements, details/summary, progress, meter, and media elements used in this project.

Contributing

Contributions are welcome! Please read Contributing for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-improvement)
3. Make your changes (HTML only — no CSS or JS in site files)
4. Validate HTML with the Nu Html Checker
5. Commit your changes (git commit -m 'Add new documentation page')
6. Push to the branch (git push origin feature/my-improvement)
7. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Author

Muhammad Shahsawar Khan

• GitHub: @your-username
• Email: muhammad@roboticela.com

Acknowledgements

• MDN Web Docs — HTML reference and best practices
• WHATWG HTML Living Standard — HTML5 specification
• W3C — Web standards and validation tools
• GitHub Pages — Free static site hosting

---

HTML Dev Docs — Demonstrating that great documentation starts with great HTML.