Leet School

{module 3}

Headings, paragraphs and lists

Your first page in HTML20 min read

What you will be able to do

  • Write headings in order, from h1 down, so that they read as a table of contents.
  • Choose between a paragraph, an unordered list and an ordered list for a piece of text.
  • Explain what a screen reader and a search engine do with headings and lists.

Why it matters

Jasmine Tutoring runs small after-school classes in Colombo, Sri Lanka. Its owner, Dilani Perera, typed the page in paragraphs. To make "Subjects" and "How to book" stand out, she made those lines bold. On her screen the page looked organised.

One parent, Mr Fernando, is blind. He uses a screen reader, the software that reads a page aloud. His screen reader can jump from heading to heading, but this page had no headings, only bold paragraphs. To find out how to book, he had to listen to every line from the top. He phoned Dilani instead, and told her why.

The page looked right and meant nothing to his software. This lesson is about writing what each piece of text is, so that people and programs can find their way around a page.

The idea

Elements say what text is, not how it looks

In module 1 you met two elements: a heading and a paragraph. The browser draws a heading large and bold, and puts space around a paragraph. That look is only the browser's default. In module 3 you will change it completely with CSS.

So you never choose an element for how it looks. You choose it for what the text is. Ask of each piece of text: is it a heading, a paragraph, an item in a list, or a step? Then use the element that says so. A program that cannot see the page, such as a screen reader or a search engine, reads only these elements.

Headings have levels

HTML has six heading elements, h1 to h6. The number is a level, not a size.

  • h1 is the title of the page's content. A page has one.
  • h2 is the heading of a main part of the page.
  • h3 is a heading inside an h2 part, and so on down.

Never skip a level. An h3 belongs inside an h2 part, so an h3 straight after the h1 leaves a gap. Read alone, in order, the headings of a page should work as a table of contents:

From index.html
<h2>Class times</h2>
<h3>Monday to Friday</h3>
<p>Classes start at <em>16:30</em>, after the school bus arrives.</p>
<h3>Saturday</h3>

"Monday to Friday" and "Saturday" are parts of "Class times", so they are one level down.

Paragraphs, and what the browser does with your line breaks

A p element is a paragraph: one or more sentences about one thing. The browser ignores the line breaks and extra spaces you type inside it. It turns each run of spaces and line breaks into a single space. You will see this in "Common mistakes". Structure comes only from elements.

Two kinds of list

A list needs two kinds of element. The outer element says what kind of list it is, and each item is an li, a list item.

  • ul is an unordered list: items whose order does not matter. The browser puts a bullet before each item.
  • ol is an ordered list: steps that happen in order. The browser puts a number before each item.
From index.html
<ol>
  <li>Send us the student's name and age.</li>
  <li>Choose a day from the times we send back.</li>
  <li>Come ten minutes early to meet the tutor.</li>
</ol>

Do not type the numbers yourself. The ol element adds them, and keeps them right when you add or remove a step.

Emphasis

Two elements mark words inside a sentence.

  • em is stress emphasis: the word you would say louder if you read the sentence aloud. "Classes start at 16:30" tells a parent that the time is the point, perhaps because they expected another one. The browser shows it in italics.
  • strong marks text that is important, such as a warning or something a reader must not miss. The browser shows it in bold.
From index.html
<p><strong>Bring the student's last school report to the first class.</strong></p>

Again, choose by meaning. If you only want text to look bold or italic, that is a job for CSS in module 3.

Who reads the structure

A screen reader can list all the headings of a page and jump to any one of them. It says how many items a list has before it reads them, so the listener knows how much is coming. A search engine reads the title and the headings to work out what the page is about. Building pages that people with disabilities can use is called accessibility, and it starts with choosing the right element.

Worked example

In your course folder, make a folder called jasmine-tutoring with a file called index.html in it. Type this page, and save it:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Jasmine Tutoring, Colombo</title>
  </head>
  <body>
    <h1>Jasmine Tutoring</h1>
    <p>Small classes after school for students aged 11 to 16.</p>
    <h2>Subjects</h2>
    <ul>
      <li>Mathematics</li>
      <li>Science</li>
      <li>English</li>
    </ul>
    <h2>Class times</h2>
    <h3>Monday to Friday</h3>
    <p>Classes start at <em>16:30</em>, after the school bus arrives.</p>
    <h3>Saturday</h3>
    <p>Classes start at 9:00 and end at 12:00.</p>
    <h2>How to book a first class</h2>
    <ol>
      <li>Send us the student's name and age.</li>
      <li>Choose a day from the times we send back.</li>
      <li>Come ten minutes early to meet the tutor.</li>
    </ol>
    <p><strong>Bring the student's last school report to the first class.</strong></p>
  </body>
</html>

Open it in your browser. This is the text on the page:

Output
Jasmine Tutoring

Small classes after school for students aged 11 to 16.

Subjects
Mathematics
Science
English
Class times
Monday to Friday

Classes start at 16:30, after the school bus arrives.

Saturday

Classes start at 9:00 and end at 12:00.

How to book a first class
Send us the student's name and age.
Choose a day from the times we send back.
Come ten minutes early to meet the tutor.

Bring the student's last school report to the first class.

In the window you also see a bullet before each subject and a number before each step. They come from ul and ol. The time is in italics and the last line is bold.

Now read the page the way a screen reader can offer it: only the headings, in order.

Output
Jasmine Tutoring
Subjects
Class times
Monday to Friday
Saturday
How to book a first class

That is a table of contents. Mr Fernando could jump straight to "How to book a first class". In the Elements panel, open the ol and you see the three li elements inside it.

Common mistakes

None of these mistakes produces an error message. The page shows something, and each mistake is found by reading the structure, not the look.

A heading chosen for its size

The h2 looked too big, so the learner used h4:

From skipped-level.html
<h1>Jasmine Tutoring</h1>
<p>Small classes after school for students aged 11 to 16.</p>
<h4>Subjects</h4>

Here is how many h2, h3 and h4 headings the page has:

Output
0
0
2

A screen reader announces "heading level 4", and its user wonders where levels 2 and 3 went. Use h2. If it looks too big, CSS will change its size in module 3.

A bold paragraph instead of a heading

This is the mistake on Dilani's page:

From bold-heading.html
<p><strong>How to book a first class</strong></p>

It looks like a heading. Here are the headings the browser found:

Output
Jasmine Tutoring
Subjects

"How to book a first class" is missing, so nobody can jump to it. If text names the part of the page that follows, it is a heading.

Steps typed on separate lines

From typed-lines.html
<p>
  1. Send us the student's name and age.
  2. Choose a day from the times we send back.
  3. Come ten minutes early to meet the tutor.
</p>

This is what the browser shows:

Output
1. Send us the student's name and age. 2. Choose a day from the times we send back. 3. Come ten minutes early to meet the tutor.

The line breaks became spaces, so the three steps run together. They are steps in order, so they belong in an ol, with one li each and no typed numbers.

Think it through

Kofi has the text for a page about Jasmine Tutoring's exam week. It has a title, a sentence about the week, a plan for each of the five days, and a list of things to bring: a calculator, two pencils and a water bottle. He must turn it into HTML.

Understand. In: plain text. Out: a page where each piece of text is in the element that says what it is, and the headings read as a table of contents.

Break down. He asks one question of each piece: is it the title, a heading, a paragraph, a step or an item?

Plan. The title is the h1. "The plan for the week" and "What to bring" are main parts, so h2. Each day is a part of the plan, so each day is an h3, with its plan in a p. The things to bring have no order, so ul.

Build. He types the skeleton and the h1, and checks it in the browser. Then he adds one part at a time and reloads after each.

Test. He reads only the headings, in order, aloud. They make sense as a table of contents. The odd case: is the sentence about the week a heading? It is short, but it is a sentence about the week, not the name of a part. It stays a p.

Reflect. He had first thought of ol for the days, because days come in order. But each day has a heading and a paragraph of its own, so each day is a part of the page. Order alone does not make a list.

At work

Before you write the headings, find out who will read the page. Dilani asked for "a page for the tutoring". That could be for students, for parents, or for schools that send students. Each reader looks for different things, in a different order. A careful developer asks:

Who opens this page most: students or parents? When a parent finds it, what do they want to know first: the subjects, the times, or the price? Do they read it on a phone? Do any of them read English as a second language?

Dilani answers: "Parents, on their phones, and they ask me about times more than anything." Now you know three things. "Class times" should come early. Sentences must be short and plain. And the steps to book are what a parent does next. One answer gave you the order of the h2 headings. You also know that one reader uses a screen reader, so the headings must be real headings.

Your tasks

Task 1: Build the page

Type the worked example into jasmine-tutoring/index.html. Add a fourth subject to the list, and a fourth step to the booking steps.

You are done when the page shows four bullets and four numbers, and you did not type any of the numbers.

Task 2: Read only the headings

Copy your page's headings onto paper, in order, and indent each one by its level. Then add a new h2 part called "Fees" with one paragraph that gives an invented price in US dollars.

You are done when your list on paper reads as a table of contents, and "Fees" is in it at the right level.

Task 3: Find the structure in a messy page

Write a page for a business you know from a short description of it, such as a menu or a list of services. Write the outline first, as a list of headings with their levels, and decide for each list whether its order matters. Then build the page.

You are done when the page has one h1, no skipped level, and at least one ul and one ol, each chosen for a reason you can say in one sentence.

Recap

  • Choose an element for what the text is, never for how it looks.
  • One h1, then h2 for main parts and h3 inside them. Never skip a level.
  • ul for items in any order, ol for steps in order, li for each item. Do not type numbers.
  • em is a word you would stress, strong is something important.
  • Screen readers and search engines read the structure. The headings in order are a table of contents.

Go deeper