HTML Foundations: Building a Semantic Document

Basic

HTML is the language we use to describe the structure and meaning of web content. In this learning resource, we will build a small document one semantic piece at a time.

2. Start with a document heading

A page normally begins with a main heading. The heading level communicates its place in the document hierarchy, so the text should describe the subject of the page rather than merely make text look large.

<h1>HTML Foundations: Building a Semantic Document</h1>

3. Write paragraphs of content

A paragraph groups related sentences into one unit of prose. Use a paragraph when your content is a paragraph—not because the browser happens to give it a particular amount of spacing.

HTML elements describe relationships and meaning. For example, the <p> element says that its content is a paragraph.

4. Add emphasis and useful inline semantics

Inline content can carry meaning too. You can make a phrase strong when it is important, use emphasis when stress matters, and use <code> when you are referring to source code.

You can also link related information. For example, visit the HTML Living Standard for the current HTML specification.

5. Organize related ideas with lists

Lists express relationships that paragraphs cannot express as clearly. An unordered list is useful when the order does not matter:

• Structure the document.

• Give content semantic meaning.

• Let CSS control presentation.

When sequence matters, use an ordered list:

1. Plan the document structure.

2. Write the semantic HTML.

3. Style it with CSS.

4. Test the result in a browser.

6. Explain terminology with a definition list

Element

A unit of HTML structure with a defined meaning and content model.

Attribute

Additional information attached to an element, such as an identifier or a relationship.

Semantic HTML

HTML chosen because it accurately represents what the content means.

7. Show source code without losing its structure

A code block is useful when the reader needs to study source rather than execute it as document content.

1
2
3
4

<article>
  <h1>Semantic HTML</h1>
  <p>Structure gives content meaning.</p>
</article>

8. Add an image with alternative text

Images are embedded content. When an image conveys information, its alternative text should communicate that information to users who cannot see the image.

9. Represent structured data with a table

Tables are for data with relationships between rows and columns. Give header cells the correct scope so those relationships remain understandable to assistive technology.

10. Keep supporting information close to the content it explains

11. Use quotes for quoted material

Good HTML describes the content you have, rather than forcing content into elements chosen for their default appearance.

12. Add short side comments with small

Some text is a short side comment rather than the main message. The copyright and licensing note below is semantic content, not merely text that happens to be styled smaller.

<p>Foxipa learning resources are free to read. <small>Content is provided under the applicable license.</small></p>

13. Use subscript and superscript for typographical meaning

Subscripts and superscripts are semantic typography, not generic ways to move text up or down. In H₂ O, the subscript changes how the formula is read, while the superscript in E = mc² carries typographical meaning.

<p>Water is H<sub>2</sub>O.</p>
<p>E = mc<sup>2</sup></p>

Do not choose sub or sup simply because you want a visual offset. The HTML Living Standard says these elements are for typographical conventions with specific meanings; when detailed mathematical structure is needed, MathML is the more expressive choice.

14. Add pronunciation or other annotations with ruby

Ruby annotations associate a piece of base text with a related annotation. They are commonly used for pronunciation guidance, especially in East Asian typography, but the relationship can represent other annotations as well.

<p>
  <ruby>漢<rt>かん</rt></ruby>
</p>

The base text stays inside ruby , while the annotation is expressed with rt . This is a structural relationship, not a generic way to position smaller text.

When fallback delimiters are appropriate, rp can surround the annotation text for user agents that do not render ruby annotations.

<p>
  <ruby>漢<rp>（</rp><rt>かん</rt><rp>）</rp></ruby>
</p>

Foxipa represents ruby as a structured inline node because the base text and annotations have an explicit semantic relationship. It should not be flattened into a visual mark or a collection of unrelated inline nodes.

15. Mark inserted and deleted text

Use ins for content that has been added to a document and del for content that has been removed. These elements describe an editorial change; their visual appearance is only a presentation of that meaning.

<p>The meeting is on <del>Tuesday</del> <ins>Wednesday</ins>.</p>

Both elements can also carry cite and datetime information when the source or time of the change needs to be recorded. Keep those details on the semantic element rather than replacing the element with a purely visual style.

16. Define terms and abbreviations

Use dfn for the defining instance of a term. When the term is an abbreviation, abbr can provide its expansion with the title attribute.

<p>The <dfn><abbr title="Web Hypertext Application Technology Working Group">WHATWG</abbr></dfn> develops web standards.</p>

The dfn element identifies where a term is defined; the surrounding paragraph, section, or definition-list group should contain its definition. The abbr element identifies an abbreviation, and its title value, when present, is the expansion—not a general tooltip.

17. Connect human-readable data to machine-readable values

Use data when the text shown to people also has a machine-readable value. The human-readable content stays inside the element, while the value attribute provides the value that software can process.

<p>There are <data value="8">eight</data> items in the set.</p>

For dates, times, and durations, use the more specific time element instead. Its datetime attribute carries the machine-readable date or time when the visible wording is different.

<p>The workshop begins on <time datetime="2026-09-15">September 15</time>.</p>

The time value is restricted to the date, time, time-zone, week, year, or duration formats defined by HTML. When datetime is omitted, the element cannot contain nested elements; its text itself must provide the date or time value.

18. Let readers reveal additional information with details

Use details for a disclosure widget that lets readers reveal additional information or controls. Its first summary child provides the label for that disclosure.

<details>
  <summary>What does semantic HTML mean?</summary>
  <p>HTML uses elements according to the meaning of their content.</p>
</details>

The details element provides the disclosure behavior natively. The summary identifies what can be revealed, while the remaining flow content becomes the disclosure body.

If the disclosure should start open, HTML can use the open attribute. Related details elements can also share a name to form an exclusive group where only one member is open at a time.

19. Group a self-contained example with figure

Use figure when a piece of flow content forms a self-contained unit that can be understood as a single item, such as an illustration, diagram, photograph, or code listing. A figcaption can provide its caption or legend.

hugo --gc --minify

The caption belongs to the figure rather than being an unrelated paragraph placed beside it. The figure itself remains part of the surrounding document flow, so use it for content that forms a meaningful unit, not merely because something needs a border or card-like appearance.

20. Separate content from presentation

A semantic document can contain deliberate editorial cues without turning those cues into CSS vocabulary. For example, this learning resource uses a callout for supplementary guidance, while its actual message remains ordinary document content.

21. Put the pieces together

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<article>
  <h1>HTML Foundations</h1>
  <p>HTML describes document structure and meaning.</p>

  <h2>Lists</h2>
  <ul>
    <li>Structure</li>
    <li>Meaning</li>
  </ul>
</article>

Notice that the HTML describes the document rather than its visual appearance. There is no instruction here to make a heading blue, add a card, or arrange a paragraph in a particular grid.

22. A quick checklist

1. Choose elements according to meaning.

2. Keep heading levels consistent with the document hierarchy.

3. Use lists for lists and tables for tabular data.

4. Provide useful alternative text for informative images.

5. Use disclosure elements such as details when information is intentionally revealed on demand.

6. Use CSS to control appearance instead of replacing semantic HTML with visual constructs.

What to learn next

Once the basic document structure feels natural, the next step is to study individual HTML elements and their content models in more depth. From there, forms, interactive elements, accessibility, and more complex document structures become much easier to reason about.