# Part 2: Semantic HTML — Headings, text content, section elements ## Introduction When I first started writing HTML, I used `

` for everything. Navigation? `

`. Article content? `

`. Page footer? `

`. It worked visually — browsers rendered it — but the page was structurally meaningless. Screen readers had no idea what was navigation versus main content. Search engines had no signal about what text mattered most. CSS ended up full of context-dependent class names just to compensate for the lack of structure. Semantic HTML solves this. Using elements that describe what content *is*, not just how it looks, makes pages accessible, maintainable, and honestly easier to write CSS for. *** ## What "Semantic" Means A semantic element clearly describes its meaning to both the browser and the developer. Compare: ```html

Home

``` Both render identically by default. The difference is in what the markup communicates: * The browser knows `

` is navigation — it can be listed by accessibility tools * Search engines understand `

` is navigational, not primary content * Other developers reading the code understand the intent immediately *** ## Headings Headings create the document outline. The browser, screen readers, and search engines all use heading levels to understand document hierarchy. ```html

Main Page Title

Section Title

Content under this section.

Subsection Title

Content under this subsection.

``` ### Rules I Follow **One `

` per page. It identifies the primary topic of the page. On a blog post, it is the post title. On a dashboard, it is the dashboard name. Do not skip levels.** If you have a `

`, the next level down should be `

`, not `

`. Skipped levels confuse the document outline and trip up screen readers. Do not use headings for visual size. If you want large bold text that is not a heading, use CSS. Do not use `

` just because it looks the right size. ```html

Created on 2024-01-15

``` *** ## Text Content Elements ### Paragraphs ```html

A paragraph of text.

``` `

` is for prose — sentences and paragraphs. Do not use it for single labels or non-prose text. ### Strong and Emphasis ```html

This is critically important.

The term idempotent means applying it multiple times gives the same result.

``` * `` — serious importance, urgency, or warning. Screen readers may emphasise this. * `` — stress emphasis, i.e., spoken emphasis that would change meaning. Screen readers may inflect this. These are semantic elements. For purely visual bold/italic without semantic meaning: ```html
This is visually bold but carries no special importance.

This is visually italic for style or a technical term.
``` ### Code ```html
Run cargo build --release to compile.

fn main() { println!("Hello, world!"); }
``` * `` — inline code, filenames, command names * `` — preserves whitespace and line breaks, for code blocks * `` together — the correct pattern for multi-line code blocks ### Quotations ```html According to the spec, the document must be well-formed. If it's stupid but it works, it's not stupid. ``` ### Abbreviations ```html HTML is not a programming language. ``` The `title` attribute provides the expansion on hover/screen reader. *** ## Lists ### Unordered List ```html First item Second item Third item ``` Use when the order does not matter (feature lists, navigation items, bullet points). ### Ordered List ```html Clone the repository Install dependencies Run the server ``` Use when sequence matters (installation steps, ranked items, table of contents). ### Description List ```html Idempotent An operation that produces the same result regardless of how many times it is applied. Atomic An operation that either completes fully or has no effect at all. ``` `` (description list) is the correct element for glossaries, metadata pairs, or term–definition structures. I use it in documentation pages where I'm presenting key-value pairs. ### Nesting Lists ```html Backend Python Rust Frontend HTML CSS ``` *** ## Structural Sectioning Elements HTML5 introduced elements that describe the role of sections in the page layout. ### `` ```html Site Name ... ``` Contains introductory content for a page or section: logos, site titles, navigation, search. There can be a `` inside `` or `` as well — each represents the introductory content for that element. ### `` ```html Home About Blog ``` For major navigation blocks. Not every group of links needs to be `` — reserve it for the primary and secondary navigation menus. ### `` ```html ``` There should be exactly **one `` per page**. It identifies the primary content, distinct from headers, footers, and sidebars. Screen readers use it to skip directly to content. ### `` ```html Building a WAF Scanner in Rust Published 2024-03-15 by Htunn When I decided to build a WAF bypass testing tool... ``` Self-contained content that makes sense on its own and could be syndicated independently: blog posts, news articles, forum posts, documentation pages. ### `` ```html Installation ... Configuration ... ``` A thematic grouping of content. Usually has a heading. Use `` when grouping related content under a heading; use `` when grouping purely for styling with no semantic meaning. ### `` ```html Related Articles Rust 101 Series ``` Content tangentially related to the primary content: sidebars, pull quotes, related links, advert zones. ### `` ```html © 2025 Htunn. All rights reserved. Privacy Contact ``` Footer content for a page or section: copyright, links, contact information. *** ## `` and `` `` and `` are non-semantic containers. Use them when no semantic element fits the purpose. ```html Title Content Status: Active ``` The rule: reach for a semantic element first. Use `` or `` only when nothing semantic applies. *** ## Page Structure Example A typical documentation page combining the elements above: ```html simple-waf-scanner — Documentation simple-waf-scanner Home Docs GitHub Getting Started Scan your first target in under 5 minutes. Installation cargo install simple-waf-scanner Basic Usage waf-scanner scan --target https://example.com Quick Reference --target URL to scan --payloads Path to custom payload file MIT License — View on GitHub ``` *** ## Summary | Element | Purpose | | ------------------------ | --------------------------------------------------- | | ``–` ` | Document outline and section headings | | `` | Prose paragraphs | | `` / `` | Semantic importance / emphasis | | `` / `` | Visual bold / italic without semantic meaning | | `` / ` ` | Inline code / code blocks | | `` / `` / `` | Unordered / ordered / description lists | | `` | Introductory content for page or section | | `` | Primary navigation blocks | | `` | Primary page content (one per page) | | `` | Self-contained, independently distributable content | | `` | Thematic grouping with a heading | | `` | Tangentially related content | | `` | Footer for page or section | | `` / `` | Non-semantic containers for styling/scripting | *** ## Up Next [Part 3](https://blog.htunnthuthu.com/getting-started/programming/html-101/html-101-part-3) covers links, images, and media — the elements that connect pages and embed content.