2.1 Semantic HTML documents

A reading-circle page needs more than text placed in a particular order. Its title should identify the page, its navigation should lead to useful destinations, and a timetable should preserve the relationship between a session and its starting time. HTML expresses those relationships so that browsers and other tools can interpret the document.

The first step is to describe the content accurately. Appearance and interaction can then be added without losing that structure. In this unit, we develop one small document and use it to distinguish source text, elements, attributes, and the structure a browser constructs.

Markup describes the role of content

HTML means Hypertext Markup Language. A browser interprets markup to construct a document. JavaScript supplies variables, branching, and event-handling logic when a page needs those behaviours. The HTML structure remains the foundation on which those behaviours act.

<a href="week2.html" class="reading-link">Second reading session</a>

Here, a is the element name, <a ...> is the start tag, and </a> is the end tag. The text between them labels the link. The href attribute supplies a destination; class assigns a reusable label that CSS or JavaScript can select. The class name itself creates no visual effect.

Most elements can contain text or other suitable elements. Their nesting expresses containment:

<p>Read the <strong>first two sections</strong> before the meeting.</p>

The strong element belongs inside the paragraph and indicates importance. A browser may display it in bold, but the meaning is more specific than a font choice. em indicates stress emphasis. The elements b, i, and u also have text-level meanings; choosing an element solely because its default appearance looks convenient confuses meaning with presentation. Use CSS when the purpose is purely visual.

Some elements are void elements: img, br, meta, and link, for example, have no end tag and cannot contain child content. Write <br> for a meaningful line break. A paragraph is still a p element; a sequence of line breaks does not establish paragraph structure.

In HTML syntax, ordinary HTML tag names are case-insensitive. Lowercase names, quoted attribute values, and consistent indentation make source easier to review. Indentation helps a human follow nesting; the tags determine the structure.

A document separates metadata from its main content

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Reading circle: session plan</title>
  </head>
  <body>
    <header>
      <h1>Reading circle</h1>
      <p>A weekly discussion of short technical articles.</p>
    </header>
    <nav aria-label="On this page">
      <a href="#schedule">Session plan</a>
      <a href="#preparation">Preparation</a>
    </nav>
    <main>
      <section id="schedule">
        <h2>Session plan</h2>
        <p>Our next discussion begins at 16:00.</p>
      </section>
      <section id="preparation">
        <h2>Preparation</h2>
        <p>Bring one question about the reading.</p>
      </section>
    </main>
    <footer>
      <p>Organised by the reading circle.</p>
    </footer>
  </body>
</html>

Metadata can also identify a stylesheet, a script, or an icon. A link element with rel="stylesheet" points to a stylesheet; an a element with href creates a navigable hyperlink. The shared idea of a URL does not make these elements interchangeable.

Comments use <!-- ... -->. A comment can explain the source without becoming rendered page text. Comments remain part of the source that a reader can inspect.

Choose structure by meaning

The first example uses semantic elements to identify the roles of its regions:

Use one visible main for the page's main content. A page header and a section header are both possible: the surrounding context determines which content a header introduces. A div is a generic grouping element when a more specific semantic role is not appropriate.

Headings h1 through h6 communicate levels of organisation. In the example, h1 names the page and h2 names each major section. A subsection of Preparation could use h3. Choosing h4 because it happens to look smaller obscures that hierarchy; styling can change the size of a correctly chosen heading.

An id identifies one element within the document. Keep each ID unique so that a fragment link identifies a clear destination. A class can be reused by many elements to describe a shared styling or scripting category. Neither an ID nor a class replaces the semantic meaning of the element carrying it.

Hyperlinks connect documents and locations

An anchor element with href represents a hyperlink. Its label should describe where the link leads, because readers may encounter that label without the surrounding paragraph.

<a href="week2.html">Second reading session</a>
<a href="#schedule">Jump to the session plan</a>

A URL can be absolute, such as https://example.test/club/week2.html, or relative to the document's base URL. With no base element changing that base, a relative URL is resolved against the document URL. The distinction between a path beginning with / and one without it matters.

The target attribute selects where navigation takes place. _self uses the current browsing context and is the usual default. _blank requests a new browsing context, which a browser commonly presents as a new tab. It does not change the destination URL.

A fragment destination must match the intended element's ID. Writing href="#Schedule" while the element has id="schedule" does not provide the exact match used in this example.

Lists and tables encode different relationships

Use an unordered list when items form a collection without a meaningful sequence. Use an ordered list when order is part of the content, such as preparation steps.

<h2>Preparation</h2>
<ol>
  <li>Read the article.</li>
  <li>Write one question.</li>
  <li>Choose a passage to discuss.</li>
</ol>

Each li is a list item. An ordered list can use start="5" to begin numbering at 5 or type="A" to use letter markers. The content should still be a sequence. Decorative marker shapes are normally a CSS concern.

Tables express relationships across rows and columns. They are appropriate for a session timetable because every row associates a topic with a time. A table should not be used merely to force unrelated parts of a page into columns.

<table>
  <caption>Reading-circle sessions</caption>
  <thead>
    <tr>
      <th scope="col">Topic</th>
      <th scope="col">Start time</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">HTML structure</th>
      <td>16:00</td>
    </tr>
    <tr>
      <th scope="row">Hyperlinks</th>
      <td>16:30</td>
    </tr>
  </tbody>
</table>

Images need both a resource and a role

An img element refers to an image resource with src. Its alt text supplies the image's textual alternative. Choose that text by asking what information the image contributes in this context.

<img src="images/reading-room.jpg"
     width="640" height="360"
     alt="A reading room with six seats around a shared table">

For an informative image, describe the relevant information. A purely decorative image can use alt="" when it adds no information that needs to be conveyed. The width and height attributes describe the image dimensions and help establish its aspect ratio before the resource loads. To try this snippet, place the image in the indicated images directory beside the document.

Raster images represent a grid of pixels. SVG represents vector graphics with shapes and coordinates. For a simple diagram, inline SVG can describe the geometry directly:

<svg viewBox="0 0 120 60" role="img" aria-labelledby="circle-title">
  <title id="circle-title">A circular reading-circle badge</title>
  <circle cx="60" cy="30" r="18" fill="currentColor"></circle>
</svg>

The circle's centre is (60, 30) in the SVG coordinate system, and its radius is 18. viewBox defines the coordinate rectangle. The title supplies a name for this graphic through aria-labelledby.

The picture element offers alternative image resources. It contains source elements followed by an img that supplies the image's text alternative and a default resource:

<picture>
  <source media="(min-width: 48rem)" srcset="images/room-wide.jpg">
  <img src="images/room-close.jpg" width="640" height="360"
       alt="The shared table in the reading room">
</picture>

When the media condition matches, the browser can select the wider composition. Otherwise the default image remains available. The picture container does not itself replace the img element.

Text characters and whitespace follow parsing rules

Some characters have a role in HTML syntax. A character reference lets the source express a character as text rather than as markup syntax:

Use the complete form, including the semicolon. For example, the source <p>2 &lt; 5 &amp; 5 &lt; 8</p> displays 2 < 5 & 5 < 8 as text.

With normal whitespace handling, runs of spaces, line breaks, and tabs in ordinary paragraph text are collapsed for display. Indenting a paragraph in the source does not indent the rendered paragraph by the same amount. A non-breaking space keeps a pair such as Week 2 together; it is not a substitute for layout spacing.

pre preserves whitespace under its default styling, making it suitable for preformatted text. It does not turn off HTML parsing. To display HTML source, escape its markup characters and place the result inside code:

<pre><code>&lt;h2&gt;Session plan&lt;/h2&gt;
&lt;p&gt;Bring one question.&lt;/p&gt;</code></pre>

The result shows the two lines of source instead of creating a heading and a paragraph. sub and sup express subscript and superscript text where that notation belongs, for example H<sub>2</sub>O and r<sup>2</sup>.

Inspect the document at two levels

View Page Source shows the HTML source delivered for the document. The browser's developer tools show the current document structure, including changes made during parsing or by JavaScript. They answer different questions: what source was supplied, and what structure exists now?

When a page looks unexpected, first check the element's role and its nesting. Then check the target attributes, resource paths, and text content. A browser may repair malformed HTML, so the presence of a visible result alone does not establish that the source describes the intended structure.

Exercises

<pre><code>&lt;p&gt;2 &lt; 5&lt;/p&gt;</code></pre>

To connect this document structure to the resources delivered by a server, return to Browsers, servers, and web resources.