Plate 1.2 · Phase 1 — Framing · 20 minutes

Text: headings, paragraphs and lists

Ninety percent of what is on the web is written text. This module is about marking it up so that a reader, a screen reader and a search engine all understand the same shape — and it hinges on one idea most beginners never get told.

Headings are an outline, not a font size

Open the front page of the New York Times. There is one banner headline. Beneath it, section headings. Beneath those, subheads on individual stories. Nobody printed two equal-sized banner headlines on one page, and nobody chose a headline's size by deciding it "looked about right" — the size follows from the rank.

HTML works exactly the same way. <h1> through <h6> are ranks in an outline. They happen to come with default sizes attached, and that coincidence is what ruins beginners: they pick <h4> because <h2> looked too big, and the page's outline silently turns to nonsense.

The three rules

• One <h1> per page. It is the title of the content — what the page is, in one line. (HTML won't stop you writing two; this is the convention every accessibility guide recommends, and the one to follow. Accessibility means making a page usable by everyone, including people who hear it through a screen reader or navigate with only a keyboard.)
• Don't skip levels on the way down. An <h2> may be followed by an <h3>, not an <h4>. Coming back up, jumping any distance is fine.
• Never choose a heading by how it looks. If it's too big, that's a CSS problem, and you'll fix it in twenty seconds in Phase 2.

Check an outline the way a screen reader does

Below is markup from a real-looking coffee shop page, written by someone choosing headings by size. Edit the left side; the outline and its problems appear on the right. Fix the warnings, then read the corrected version.

Paragraphs, and the mistake everyone makes first

A paragraph is <p>…</p>. That's the whole story. But because Module 1.1 taught you that pressing Enter does nothing, there is a powerful temptation to reach for <br> — the line break — to separate blocks of text. Don't.

<p>We roast on Tuesdays.</p>
<p>Orders ship on Thursdays.</p>

<p>We roast on Tuesdays.<br><br>
Orders ship on Thursdays.</p>

<br> has exactly one honest use: a line break within a single block of text where the break is part of the content. A postal address, a line of a poem, a song lyric. If the break is decorative or is really separating two ideas, you want two elements instead.

Words that carry meaning

Some inline elements exist to say what a piece of text is, not what it should look like. The pairs below look identical on screen but carry different meaning — to search engines, to translation and reading tools, and to the next developer. (Most screen readers read them in the same voice by default, so don't rely on them for spoken emphasis.)

The honest summary: use <strong> and <em> by default, because nearly every time you want bold or italic you also mean importance or emphasis. Keep <b> and <i> for the narrow cases where you truly mean "different, but no more important."

Lists: three kinds, and choosing between them

If content reads like a list, mark it as a list. A screen reader announces "list, five items" and lets the user skip it — a service you get free, and lose entirely if you fake a list with dashes and line breaks.

Inside <ul> and <ol>, the only thing allowed as a direct child is <li>. Anything else goes inside an <li>. That single rule is behind the most common list bug there is:

<ul>
  <li>Espresso
    <ul>
      <li>Single</li>
      <li>Double</li>
    </ul>
  </li>
  <li>Filter</li>
</ul>

<ul>
  <li>Espresso</li>
  <ul>
    <li>Single</li>
  </ul>
  <li>Filter</li>
</ul>

Two attributes worth knowing on <ol>: start="5" begins the numbering somewhere other than 1 — useful when a list continues after an interruption — and reversed counts down, for a countdown of finalists.

Which list is it?

Six pieces of content. Decide before you click.

Characters that need escaping

Three characters mean something to HTML, so writing them literally can confuse the browser. Write these instead:

These are called entities. There are hundreds; you will use these four and look up the rest when you need them.

Three things beginners get wrong

1. Choosing a heading level by its size. The whole module in one sentence. Rank first, size later.

2. Using <br><br> where two paragraphs belong. Identical on screen, structurally false, and impossible to space properly later.

3. Writing lists as plain text with dashes. "- Espresso" typed into a paragraph is not a list to anything except a sighted reader. One minute of markup buys you announcement, navigation and styling.

Words you now own

heading level

The rank of a heading, h1 through h6.

document outline

The structure your headings create — what screen readers and search engines navigate.

semantic

Markup chosen for what content means rather than how it looks.

block element

Starts on a new line and fills the width: <p>, <h2>, <ul>.

inline element

Sits within a line of text: <strong>, <em>, <code>.

unordered list

<ul> — order doesn't matter.

ordered list

<ol> — order is the information.

description list

<dl> with <dt> terms and <dd> descriptions.

entity

A code like & standing in for a character HTML would otherwise misread.

<h1>Maria Lopez</h1>
<p>I'm learning web development, one module at a time.</p>

<h2>What I'm learning</h2>
<ol>
  <li>Ground Floor</li>
  <li>HTML</li>
  <li>CSS</li>
  <!-- …and so on -->
</ol>
<p>
  <strong>I practice every weekday.</strong> It's the
  <em>habit</em> that matters, not the hours.
</p>

<blockquote>
  <p>The best way to predict the future is to invent it.</p>
</blockquote>
<p>— Alan Kay</p>

<h2>How to reach me</h2>
<ul>
  <li>Email</li>
  <li>LinkedIn</li>
  <li>GitHub</li>
</ul>

h1  Maria Lopez
  h2  What I'm learning
  h2  How to reach me