HTML Basics

HTML labels the parts of a page so the browser can build its structure. A heading, a paragraph and a link have different meanings, even before you add any styling. HTML describes content; CSS controls its appearance, and JavaScript adds behavior.

Read an element

In <p>The workshop opens at noon.</p>, <p> is the start tag, the sentence is the content, and </p> is the end tag. The whole thing is a paragraph element. The slash marks the end tag. Use lowercase element names so your source stays consistent, even though HTML also accepts uppercase names.

An attribute adds information inside a start tag:

<a href="hours.html" title="Workshop opening hours">Opening hours</a>

Here href supplies the destination and title supplies advisory text. Separate attributes with spaces and put their values in straight quotation marks. Their order does not change their meaning. Quotes keep a value together: class="intro note" gives two class names, while class=intro note is read as one class value and a separate attribute named note.

Put elements inside one another

A paragraph can contain a word with strong importance:

<p>Bring your <strong>booking number</strong>.</p>

Open the paragraph, open the strong element, close the strong element, then close the paragraph. Close the most recently opened element first. The paragraph is the parent, and the strong element is its child. Children and everything inside them are descendants. The browser organizes these relationships into the DOM, or Document Object Model, a tree of the page's content.

Not every element can go inside every other element. For example, a list cannot sit inside a paragraph. Indentation helps you see nesting, but adding spaces cannot make an invalid parent-child relationship valid.

Recognize special kinds of elements and attributes

Void elements have no content and no end tag. Examples are <img>, <br>, <hr>, <meta> and <link>. Write <br>, without </br>. A trailing slash in <br /> has no effect in HTML.

A boolean attribute is on when it is present. For an ordered list, reversed makes the numbering count down. Writing reversed="false" still leaves the attribute present, so it still counts down. Remove the attribute to turn it off.

Some attributes work across elements:

Read source spacing and comments

In ordinary text, several spaces, tabs or source line breaks collapse to one space. Writing a paragraph over three source lines still gives one paragraph on screen. Use elements to express structure and source indentation to make it readable.

A comment looks like <!-- Menu starts here -->. It is hidden from the displayed page but visible in the source. Never put passwords or private information in comments. Comments cannot be nested: the first --> ends the comment.

A complete page separates information about the document from the content people read. Start with a small, consistent skeleton, then add the page's own title and body content.

Build the skeleton

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Opening Hours – Harbor Café</title>
  </head>
  <body>
    <h1>Harbor Café</h1>
    <p>Open every day except Monday.</p>
  </body>
</html>

<!DOCTYPE html> tells the browser to use standards mode, its normal modern rendering rules. It is a declaration, not an element. Leaving it out can trigger quirks mode, which imitates older browser behavior and can change layout and sizing.

<html> is the root element. Its two element children are <head> and <body>. The head holds metadata, information about the page. The body holds the visible content. An <h1> belongs in the body, even if the browser appears to recover when you put it in the head.

Give the page its identity

The <title> appears in the browser tab, bookmarks and history. Search engines may also use it for a result headline. Give each normal page exactly one title, inside the head. Put the specific topic first, followed by the site name, such as "Opening Hours – Harbor Café". The visible <h1> and the document title are separate elements with different jobs.

Place <meta charset="utf-8"> first in the head. The entire declaration must be within the file's first 1,024 bytes. An early declaration lets the browser discover how to decode text before it has read much of the page.

The viewport line asks mobile browsers to use the device width for layout and an initial zoom of 1. Without it, many use a wide virtual desktop viewport and shrink the result, making text appear small. This line prepares the document for mobile layout; the page's styling still determines how its content fits.

Connect other page resources

Common additions to the head include:

<meta name="description" content="Fresh bread, coffee and lunch by the harbor.">
<link rel="icon" href="favicon.png">
<link rel="stylesheet" href="styles.css">
<script src="app.js" defer></script>

The description summarizes the page and may appear in search results. The icon supplies the tab image. The stylesheet link connects a CSS file. The script element connects JavaScript; defer delays its execution until the document has been parsed. Unlike <link> and <meta>, <script> needs an end tag even when its content is empty.

Save a web page file

Save plain text in a code editor with an .html extension. A word processor can add formatting that does not belong in an HTML source file. A folder's default page is conventionally index.html; most web servers send it when someone requests the folder address.

Choose lowercase names with hyphens, such as opening-hours.html. Spaces become %20 in URLs, and many servers distinguish uppercase from lowercase. Check that the editor did not save your page as index.html.txt. After saving, open the HTML file in the browser and refresh it when you make a change.

The language of text and the way its characters are stored answer different questions. A browser needs both to present the page correctly, especially when the content includes accents or more than one writing system.

Name the language of the content

Write the main language on the root element: <html lang="en">. Screen readers can choose pronunciation from this information, and browsers can use it for translation and spelling. A language tag begins with a language code. An optional second part can name a region or script.

The tag describes the content, not the visitor's location. uk means Ukrainian, so it is not the tag for English in the United Kingdom.

Mark a change of language on the nearest suitable element:

<p>Our host said <span lang="fr">bon appétit</span>.</p>

Only the French phrase receives French pronunciation. For a whole quotation, the language can go on its <blockquote>. A right-to-left page also needs its base text direction, for example <html lang="ar" dir="rtl">. Arabic letters still run right to left without that attribute, but the base direction affects paragraph alignment, punctuation and mixed-direction text.

Match the saved bytes and the declaration

A character encoding maps characters to stored bytes. UTF-8 can represent all Unicode characters, including accented letters, other scripts and emoji. HTML documents use UTF-8.

There are two steps: save the actual file as UTF-8 in the editor, and declare <meta charset="utf-8"> early in the head. The declaration tells the browser how to read bytes; it does not convert a file saved in another encoding. A server's encoding declaration in its Content-Type header takes precedence over the meta element.

An encoding mismatch often leaves a clue. UTF-8 text "Café" read as Windows-1252 can become "Café" because the two bytes for "é" are interpreted separately. A Windows-1252 file read as UTF-8 can instead show "Caf�" because the byte is invalid in UTF-8. Check the editor's encoding and the browser's received document information before replacing individual letters.

Display characters that HTML uses as syntax

To show literal tag-like text, write character references:

<p>Use &lt;p&gt; for paragraphs.</p>

The page displays "Use

for paragraphs." The < must be represented as < so the browser does not begin a tag. Each named reference starts with & and ends with ;.

For example, 10 km keeps the number and unit on the same line. Ordinary accented characters can be typed directly into a UTF-8 file; you do not need a separate reference for every accent.

A browser tries to display a page even when its HTML is wrong. That helpful recovery can hide errors, so checking a page means examining both the source you wrote and the structure the browser built.

Compare source with the DOM

View Page Source shows the HTML received by the browser. The Elements or Inspector panel in developer tools shows the DOM, the parsed tree the browser is using. The browser may have closed an element early or moved content to another place during parsing.

Open the inspector by right-clicking the page and choosing Inspect, or use your browser's developer-tools shortcut. Select a displayed element and look at its parent and children. Then find the same area in the source. Differences can explain unexpected spacing, links that extend too far or styling applied to the wrong elements.

Trace an automatic repair

Suppose you write:

<p>Our soups:
  <ul>
    <li>Tomato</li>
    <li>Lentil</li>
  </ul>
</p>

A paragraph accepts text-level content, not a list. On reaching <ul>, the browser closes the paragraph. The list becomes a separate block. The final </p> has no open paragraph to close, so parsing can create an extra empty paragraph.

The repair you want belongs in the source:

<p>Our soups:</p>
<ul>
  <li>Tomato</li>
  <li>Lentil</li>
</ul>

Move the paragraph's end tag before the list. The DOM can now express the intended relationship without error recovery.

Use an HTML checker

The W3C Nu Html Checker accepts a page address, a file upload or pasted HTML. It reports errors and warnings with locations. Start with the first error, fix it, and run the checker again. A single missing quotation mark may cause many later messages, so editing every reported line at once can waste effort.

For example, <a href="about.html> lacks the closing quote. The browser can treat following markup as part of the attribute value. Fixing the quote may remove several later errors. Similarly, a missing </a> can make unrelated text join the link.

Look especially for:

• Elements closed in the wrong order or misspelled names such as <pargraph>.
• The same id used twice on one page.
• An <li> outside its list.
• An image with no alt attribute.
• Visible content placed in the head.

Check meaning as well as syntax

A clean checker result tells you that the tested markup follows its rules. It cannot decide whether "Click here" is useful link text or whether an image's alt text gives the right information. Read the page in order and check those choices yourself.

Before finishing a page, check the doctype, document language, early UTF-8 declaration and specific title. Review heading levels, unique ids, image alternatives and link destinations. Open the page in at least two browsers and follow its links. A valid relative path can still point to a missing file, which a syntax check alone will not discover.

Headings give readers a map of the page. Paragraphs hold related sentences within that map. Choose their elements from the content's structure, then let CSS set their appearance.

Make a heading outline

HTML has six heading levels, <h1> through <h6>. Use one <h1> for the page's main topic, <h2> for its main sections and <h3> for parts within an <h2> section. Most pages need only a few levels.

<h1>Growing Basil at Home</h1>
<p>Basil grows well on a sunny windowsill.</p>
<h2>Planting</h2>
<p>Sow the seeds 0.5 cm deep in moist soil.</p>
<h2>Care</h2>
<h3>Watering</h3>
<p>Water when the top of the soil feels dry.</p>
<h3>Harvesting</h3>
<p>Pick the top leaves first.</p>

Read just the headings. "Planting" and "Care" are equal main sections. "Watering" and "Harvesting" belong under "Care". This outline remains useful when a screen reader lists the headings or when a reader scans the page quickly.

A heading can go down only one level from the previous heading: after <h1>, use <h2>, not <h3>. Going back up can skip several levels. An <h2> after an <h4> starts a new main section. Heading levels follow the whole document, including content inside sections and articles.

The HTML standard permits multiple top-level headings, but one main <h1> is the common, clear pattern. Do not choose <h4> just because its default text is smaller. A bold paragraph may look like a heading, but it will not appear in a screen reader's heading list.

Separate a subtitle from a section

A tagline describes the heading beside it; it does not introduce a new section. Group a heading and subtitle in <hgroup>:

<hgroup>
  <h1>Harbor Café</h1>
  <p>Fresh bread every morning</p>
</hgroup>

The paragraph remains a subtitle. Making it <h2> would incorrectly place it in the page outline as a main section.

Use paragraphs for related sentences

A <p> element holds a paragraph. Start a new paragraph when the subject or step of the explanation changes. Browsers add visible space around paragraphs by default.

Pressing Enter in ordinary HTML source does not create a new displayed paragraph. Likewise, empty <p> elements are not a spacing tool. Keep the structure meaningful and set extra space with CSS.

Choose a break by meaning

For an address, <p>Harbor Café<br>12 Quay Street<br>Port Town</p> keeps the lines together as one paragraph. Repeated <br> elements between ordinary paragraphs confuse content structure with spacing. A horizontal line drawn by <hr> expresses a topic change; choose it because of that meaning, not simply to decorate the page.

Text elements tell the browser what a word or passage means. Their default bold, italic or indented appearance is only a starting style. Choose the meaning first.

Distinguish stress, importance and attention

Moving the emphasis in "I did lock the door" changes what the speaker is correcting. Strong importance does a different job: a warning matters regardless of how the sentence is spoken. Use CSS when you only want a visual style.

Mark quotations and their sources

A long quotation uses <blockquote>. Its optional cite attribute gives a source URL, but that address is not displayed automatically. Put a visible attribution outside the quotation:

<blockquote cite="https://example.com/interview">
  <p>The garden is open to everyone.</p>
</blockquote>
<p>From <cite>A Conversation About the Garden</cite>.</p>

<cite> marks the title of a work, not a person's name. A short quotation inside a sentence uses <q>, and the browser supplies the quotation marks. Do not type a second pair around the same words.

An abbreviation can use <abbr title="World Health Organization">WHO</abbr>. Also write its full form visibly the first time it appears. A tooltip alone is hard to access on touchscreens and is not a reliable explanation for every reader.

Show code and preserve its spacing

<code> identifies a short piece of code within a sentence. For a block whose spaces and line breaks matter, combine it with <pre>:

<pre><code>&lt;p&gt;Welcome.&lt;/p&gt;</code></pre>

The reader sees the literal paragraph markup. <pre> preserves formatting, but it does not switch off HTML parsing. You must still represent < as < and an ampersand as & when they should appear as text. Otherwise a code example may be interpreted as actual page markup.

Mark dates, notation and other useful meanings

<sub> and <sup> express subscript and superscript where the notation needs them: H<sub>2</sub>O and m<sup>2</sup>. They are not tools for making unrelated text smaller.

<time> connects readable date or time text to a machine-readable value:

<time datetime="2026-03-14">March 14, 2026</time>

The datetime value uses year-month-day. A time can use the 24-hour value 14:30, even if the visible words say "2:30 p.m.".

Use <mark> for text highlighted because it is relevant in the current context, such as a search match. <small> holds side comments or fine print. A <span> carries no built-in meaning; it is useful for a language attribute or a styling hook within a line.

A real list gives related items a shared structure. Its markup lets readers hear that they are entering a list and how many items it contains. The kind of list depends on what the items mean.

Choose the list type

Use <ul> for items whose order does not change their meaning, such as ingredients. Use <ol> for a sequence or ranking where order matters. Both contain list items marked with <li>.

<ol>
  <li>Boil the water.</li>
  <li>Add the pasta.</li>
  <li>Cook for 10 minutes.</li>
</ol>

Reversing these steps would change the instructions, so an ordered list fits. A browser normally shows numbers for <ol> and bullets for <ul>. CSS can change those markers; the meaning of the list stays the same.

Do not fake a list with typed dashes and line breaks. Those characters can look similar, but they do not tell a screen reader that the items form a list. A navigation menu often uses an unordered list, while a breadcrumb trail uses an ordered list because its path has a sequence.

Nest a list within its item

In ordinary list content, the direct element children of <ul> and <ol> are <li> elements. Do not place a paragraph or another list directly between them. The standard also allows script-supporting elements, but those do not replace list items.

A nested list belongs inside the item it describes:

<ul>
  <li>Fruit
    <ul>
      <li>Apples</li>
      <li>Pears</li>
    </ul>
  </li>
  <li>Vegetables</li>
</ul>

First open the "Fruit" item. Add its nested list, close that list, then close the "Fruit" item. Now "Apples" and "Pears" are structurally attached to "Fruit". Putting the inner <ul> after the parent's </li> would lose that relationship. An <li> can also contain paragraphs, links and images.

Control meaningful numbering

An ordered list can continue or reverse a count:

reversed is boolean. It stays enabled in reversed="false"; remove it to resume counting upward. With type, the values 1, a, A, i and I select common numbering forms. Use a meaningful marker form when text elsewhere refers to a specific label, such as clause "b".

Pair terms and descriptions

A description list uses <dl>, with <dt> for a term or name and <dd> for its description or value:

<dl>
  <dt>Opening time</dt>
  <dd>08:30</dd>
  <dt>Closing time</dt>
  <dd>17:00</dd>
</dl>

One term may have several descriptions, and several terms may share one description. A group can be wrapped in a <div>. Use this structure for name-value relationships, such as a glossary or product details, rather than forcing those pairs into unrelated bullet items.

A link connects content to a destination. The browser works out that destination from the address you put in href, so choosing the right kind of URL is part of writing the link.

Write an anchor

<a href="https://www.w3.org/">World Wide Web Consortium</a>

The <a> element is an anchor. Its href is the destination and its content is the clickable link text. An anchor without href is a placeholder, not a working hyperlink. An image can also be its content.

An absolute URL supplies a scheme and domain, as in https://example.com/guide/. Use it to link to another website. href="www.example.com" lacks a scheme, so the browser treats it as a relative file path; it does not mean "open that website".

Work from the current folder

A relative URL starts from the current page's location. Consider this site:

site/
  index.html
  about.html
  recipes/
    index.html
    soup.html
  images/
    logo.png

From the home page, about.html reaches the neighboring About page and recipes/soup.html enters the recipes folder. From recipes/soup.html, the same about.html would look inside recipes/, where there is no such file.

Work through the path from recipes/soup.html to the logo:

1. The starting folder is recipes/.
2. ../ moves up to the site folder.
3. images/ moves into the image folder.
4. logo.png names the file.

The finished path is ../images/logo.png. Each additional ../ moves up one more folder. By contrast, index.html from the soup page reaches the recipes index, not the site's home page.

A root-relative URL starts with /, such as /about.html. On a web server it starts at the website root, whatever folder the current page uses. Opened directly from disk, that slash refers to the filesystem root, so it does not identify your project's site folder. Use ordinary relative paths for pages you also test directly from disk.

Paths use forward slashes and must match file names and capitalization. Many servers treat Soup.html and soup.html as different files. A folder link such as recipes/ normally asks a server for its default file, commonly index.html; direct disk browsing may show a folder listing.

Jump to a part of a page

<a href="#watering">Watering</a>
<h2 id="watering">Watering</h2>

The fragment begins with # in the URL. The target's id has no # and must match exactly. For another page, combine them: basil.html#watering. An empty fragment # goes to the top. #top also goes to the top when no matching element is found.

Open an email or phone destination

mailto:info@example.com asks the visitor's email app to compose a message. A subject can be included as mailto:info@example.com?subject=Table%20booking, with the space encoded as %20. tel:+15555550123 supplies a telephone destination in international format. The visible phone number may contain spaces even though this href does not.

A useful link tells a person what to expect before they follow it. Its text, destination and opening behavior work together, including when the link is read by itself in a screen reader's link list.

Name the destination

Compare these links:

Keep link text brief but specific. If two links have the same text, make them lead to the same destination. A bare URL is usually harder to read than a description, although an email address is useful link text when the address itself is the information.

A title tooltip cannot repair unclear visible wording. Touchscreen users may never see the tooltip, and keyboard access to it is unreliable. Put the important destination information in the link's actual content.

Signal files and downloads

<a href="menu.pdf" download="harbor-cafe-menu.pdf">Lunch menu (PDF, 2 MB)</a>

The text identifies the file type and size. The download attribute asks the browser to save the file and suggests a file name. It does not convert a page into a PDF. For ordinary web file links, the destination must be on the same origin for download to apply; special blob: and data: URLs are also supported. Browser settings and server headers can affect the final behavior, so the attribute is a request, not a promise of one exact dialog.

Let people control new tabs

Ordinary links open in the current browsing context, where the Back button can return to the previous page. target="_blank" requests a new tab or window. The new tab does not have the original tab's Back history, and a visitor may not notice the switch.

Use a new tab only when it serves a clear purpose, and announce it in the text:

<a href="https://example.com/archive" target="_blank" rel="noopener">Archive (opens in a new tab)</a>

Modern browsers give _blank links the protection of noopener: the opened page cannot use window.opener to control the original page. Writing rel="noopener" explicitly also covers older behavior. noreferrer additionally suppresses referrer information. nofollow communicates a search-engine relationship, not a navigation destination.

Make image links and larger links understandable

When an image is the only link content, its alt text supplies the link's name:

<a href="index.html">
  <img src="logo.png" alt="Harbor Café home page">
</a>

The useful information is where the link goes. Describing only the logo's colors would not name its destination.

An anchor can wrap a larger card containing a heading and paragraph, but it cannot contain another link or a button. Nested interactive controls give competing destinations or actions within one control.

A link goes somewhere: a page, a file or a page section. A button performs an action, such as opening a menu. href="#" is a top-of-page link; it is not a substitute for a button that performs an action.

Navigation helps people find both the site page they want and the part of a long page they need. HTML can identify these groups so people using assistive technology can find them directly.

Give major navigation a region

Use <nav> around a major group of navigation links. A site menu commonly contains an unordered list:

<nav aria-label="Main">
  <ul>
    <li><a href="index.html">Home</a></li>
    <li><a href="menu.html" aria-current="page">Menu</a></li>
    <li><a href="contact.html">Contact</a></li>
  </ul>
</nav>

This markup belongs on the menu page: aria-current="page" identifies the link to the page currently shown. On the Contact page, move that attribute to the Contact link. Do not mark a section's index as the current page when the reader is viewing a different page inside that section.

The list makes the number and grouping of the links available to screen readers. Without CSS, the menu's items stack vertically. The <nav> element does not automatically arrange them in a row. A few unrelated footer links usually do not need a navigation region of their own.

Keep menus consistent across pages

Use the same items in the same order and location throughout the site. In a static HTML site, copying the menu means updating every copy when its contents change.

Check destinations from each page's actual folder. From recipes/soup.html, the home link is ../index.html; index.html would reach the recipes index. The words in the menu can stay the same while the relative paths change. A server-based site can use root-relative paths to avoid that folder dependence.

Build a table of contents

A contents list links to headings in the current page:

<nav aria-label="Contents">
  <ol>
    <li><a href="#planting">Planting</a></li>
    <li><a href="#care">Care</a></li>
  </ol>
</nav>
<h2 id="planting">Planting</h2>

Each fragment must match one unique id. Add a corresponding heading with id="care" for the second link. When several navigation regions have different jobs, labels such as "Main" and "Contents" let screen reader users distinguish them.

A breadcrumb trail is another kind of navigation. It shows a path such as "Home › Recipes › Tomato Soup". Use <nav aria-label="Breadcrumb"> with an ordered list and place the current page last. The order expresses the path through the site.

Provide a shortcut past repeated content

Put a skip link first in the body:

<a href="#main-content">Skip to main content</a>

Its target is the main region, written as <main id="main-content">. Keyboard users can follow that link to bypass a repeated menu. Keep the target id unique and spelled exactly as in the fragment. A skip link is a working navigation aid even before CSS changes its presentation.

An image in HTML remains a separate resource. The page tells the browser which file to fetch, how much space to reserve and what text can replace the image.

Add an image

<img src="images/harbor.jpg" alt="Fishing boats moored in the harbor at sunset" width="1200" height="800">

<img> is void, so it has no end tag. src gives a file address, with the same path rules used for links. alt provides a text alternative. If the picture fails to appear, check the folder, capitalization and file extension in src. A .jpg path does not identify a .png file, and .JPG can differ from .jpg on a server.

The image's bytes are not stored inside this HTML element. The browser downloads the file separately. Changing the HTML width does not make that downloaded file smaller.

Choose a format that fits the content

Current major browsers support WebP and AVIF. Choose an image based on the content and resulting file size, not only its extension. Lossy compression discards some detail to save space; lossless compression keeps the original image data.

Reserve the correct shape

The width and height attributes are whole numbers in CSS pixels, with no unit in the value. Write width="1200", not width="1200px". They let the browser reserve space before the file arrives, reducing layout shifts, where text jumps as an image loads.

A 1200 × 800 image has a 3:2 shape. Both width="1200" height="800" and width="600" height="400" preserve it. The second pair halves both dimensions. A 600 × 600 pair forces a square and distorts the picture. CSS can later control the displayed dimensions while preserving the ratio.

Reduce the file before using it

A phone photo at 4000 × 3000 has 12 million pixels and can occupy several megabytes. Resize it near its largest intended display size and choose sensible compression before adding it to the site. Otherwise every reader downloads the large file even when the page shows a tiny thumbnail.

For images further down a long page, loading="lazy" lets the browser wait until the visitor gets near them. Keep an immediately visible banner or main image on normal loading, since delaying it can make the page's first view slower.

Use images you own, have permission to use or can reuse under their license, with any required credit. Keep site images in your own site folder so another site's file changes do not break them. Content images belong in HTML; purely decorative background textures are usually handled by CSS.

Alt text supplies the information a person needs when they cannot see an image. A caption supplies visible context for everyone. Choosing both begins with the image's purpose on this particular page.

Describe the useful information

For a photo that helps readers understand a place, describe what matters: alt="The café's terrace with six tables overlooking the harbor". A long inventory of every object is rarely useful. You usually do not need "Image of" because screen readers already announce the image role. A medium can matter, though, as in "Watercolor painting of the harbor".

Context changes the useful alternative. On an adoption page, the important details might identify a dog. On a park's visitor page, the same photo might communicate that dogs are welcome on the lawn. Ask what information a reader would lose if the image disappeared.

For a chart, give its main message and place detailed data nearby. For example, alt text can state that website visits rose from 1,200 in January to 3,000 in March. The surrounding text can give the full figures. A photographed sign or another image of text needs the relevant words in its alternative.

Distinguish informative, decorative and functional images

An empty alt value is a deliberate instruction to skip a decorative image. Omitting the attribute is different: some screen readers may announce the file name instead. Use an alt attribute on every image you author.

A logo that is the only content of a home link needs a useful link name, such as "Harbor Café home page". The reader needs to know the destination, not just that the logo contains blue waves. title is not a substitute: its tooltip is not reliably available to keyboard, touchscreen or screen reader users.

Add a caption with figure

<figure>
  <img src="images/old-harbor.jpg" alt="Sailing ships crowded along a stone quay" width="1000" height="667">
  <figcaption>The harbor around 1900. Photo: Port Town Archive.</figcaption>
</figure>

<figure> groups self-contained content and its optional visible caption. <figcaption> is the first or last child of the figure, with at most one caption per figure. A figure may hold several images, a code sample, a quotation or a diagram; it is not limited to photographs.

In this example, the alt text replaces what the photograph shows. The caption supplies the date and credit. Copying the whole caption into the alt text would make a screen reader repeat that text without explaining the picture. A caption that merely says "Figure 1" also does not replace an image description.

A page contains regions with different jobs: an introduction, navigation, its unique content and supporting information. Semantic elements name those jobs so the structure is useful beyond its visual layout.

Name each region

A site header often contains a logo and menu. An article header can instead hold its heading, author and date. A footer can include contact details, related links or a copyright line. These elements identify roles, not a fixed set of words.

Keep the main content distinct

A normal page uses one visible <main>. Its content is unique to the page, so repeating site navigation belongs outside it. Do not place main inside an article, section, aside, header, footer or nav. A recipe article can go inside main, not the other way around.

An aside is for supporting material that is only indirectly related. A set of related recipe links can be an aside; an essential step in the recipe cannot. The name "aside" does not place the content in a side column. Without CSS, these regions normally stack in source order.

<body>
  <header>
    <p>Harbor Café</p>
    <nav>...</nav>
  </header>
  <main>
    <h1>Our Menu</h1>
    <p>Everything is baked fresh each morning.</p>
  </main>
  <aside>
    <h2>Today's special</h2>
    <p>Tomato soup with fresh bread.</p>
  </aside>
  <footer>
    <p>&copy; 2026 Harbor Café</p>
  </footer>
</body>

The menu page's unique content sits in main. The surrounding site information stays outside it. The source reads sensibly from top to bottom before any columns, colors or positioning are added.

Understand landmarks

A landmark is a region assistive technology can expose as a navigation destination. Main and nav provide landmarks. A page-level header provides the banner landmark, and a page-level footer provides the content-information landmark. A header or footer nested inside an article, aside, main, nav or section does not provide those page-level landmarks.

An aside normally has a complementary role. A nested aside can still have that role; nesting it in an article does not by itself remove the meaning. Use it only for appropriate supporting content and keep the page's regions understandable.

<search> identifies a region containing search or filtering controls and results. It creates a search landmark and is supported in current major browsers. It is distinct from nav: searching for content and choosing a known navigation link are different jobs.

A header cannot contain a header or footer, and a footer cannot contain either one. Separate page-level regions from the headers and footers that belong to individual articles. Choosing the right names provides useful structure even when all the regions currently look like ordinary blocks.

A semantic choice tells readers what a block of content is. Ask how the content relates to the page before choosing a container; two boxes that look alike can need different elements.

Test whether the content stands alone

An article is a self-contained composition that could be shared or reused separately. A blog post, recipe, news story or reader comment can meet that test. An article usually has its own heading, but having a heading alone does not make a block an article.

A section groups one theme within a larger whole, normally with a heading. "Opening hours" and "How to find us" can be sections of a contact page. If the block has no clear theme and you cannot give it a sensible heading, section is probably the wrong choice.

<article>
  <h2>Growing Basil at Home</h2>
  <section>
    <h3>Planting</h3>
    <p>Choose a sunny place for the pot.</p>
  </section>
  <section>
    <h3>Care</h3>
    <p>Check the soil regularly.</p>
  </section>
</article>

Here the article is one complete growing guide, while its sections divide the guide into themes. This example fits a page whose main <h1> appears before the article.

Nesting also works in the other direction. A "Latest news" section may contain several independent articles. Comments can be articles nested in the article they respond to. The content relationship decides the nesting.

Keep heading levels in the page outline

A section does not restart heading levels. If a page uses <h1> for its topic and <h2> for a themed group, use <h3> for articles inside that group. Do not put a new <h1> in every nested section. Browsers and screen readers use the heading levels you actually write; a section wrapper does not repair a skipped level.

Use neutral wrappers when no meaning fits

<div> is a neutral block wrapper. <span> is a neutral wrapper within a line of text. They provide hooks for a class, a language attribute or later styling without claiming a special content role.

<p>Try <span lang="fr">pain au chocolat</span> today.</p>

The span identifies the French passage without introducing a new block. Building the entire page from generic divs loses useful roles, but turning every div into a section invents themes that are not present.

Choose by asking what the block does:

1. Is it the page's unique content? Use main as the outer region.
2. Is it a major navigation group? Use nav.
3. Could it stand as a complete composition? Consider article.
4. Is it a themed part with a heading? Consider section.
5. Is it indirectly related support? Consider aside.
6. Is it just a wrapper? Use div, or span within text.

<address> has a particular meaning too: contact information for the nearest article or for the page. An email link in a site's contact footer can belong there. A postal address mentioned as a historical fact or event venue does not become contact information merely because it contains a street name.

Plan the roles and reading order before typing a complete page. A simple wireframe names the regions, while a heading outline names the content inside them. Together they guide the elements and their nesting.

Map the content

For a recipe page, put the repeated site name and menu in a header, the recipe in main and the site information in a footer. The recipe is self-contained, so an article fits inside main. Its outline is "Tomato Soup" with "Ingredients" and "Method" beneath it.

The page below lives in a recipes/ folder. Its home page and image folder are one folder up:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Tomato Soup – Harbor Café Recipes</title>
  </head>
  <body>
    <a href="#main-content">Skip to main content</a>
    <header>
      <p><a href="../index.html">Harbor Café</a></p>
      <nav>
        <ul>
          <li><a href="../index.html">Home</a></li>
          <li><a href="index.html">Recipes</a></li>
        </ul>
      </nav>
    </header>
    <main id="main-content">
      <article>
        <h1>Tomato Soup</h1>
        <p>Published <time datetime="2026-03-14">March 14, 2026</time></p>
        <figure>
          <img src="../images/tomato-soup.jpg" alt="A bowl of red tomato soup with a swirl of cream" width="1200" height="800">
          <figcaption>Ready in 30 minutes.</figcaption>
        </figure>
        <h2>Ingredients</h2>
        <ul>
          <li>1 kg ripe tomatoes</li>
          <li>1 onion</li>
          <li>500 ml vegetable stock</li>
        </ul>
        <h2>Method</h2>
        <ol>
          <li>Chop the onion and tomatoes.</li>
          <li>Simmer them in the stock for 20 minutes.</li>
          <li>Blend until smooth.</li>
        </ol>
      </article>
    </main>
    <footer>
      <p>&copy; 2026 Harbor Café</p>
    </footer>
  </body>
</html>

Follow the choices in the code

The skip link is first in the body and targets the main region's unique id. The header contains the repeated site identity and navigation. The recipe article has the page's single main heading, followed by two equal <h2> sections.

Ingredients use an unordered list because changing their display order does not change what is required. The method uses an ordered list because the steps form a sequence. The photo's alt text replaces the picture; its caption supplies preparation context.

../index.html goes up to the home page. index.html stays in the recipes folder. Neither menu link is marked aria-current="page", because the displayed page is the soup recipe, not either index.

Check the finished page

Read the source from top to bottom. Its order should work for a keyboard user and a screen reader before CSS rearranges anything. Check the title, heading outline, single visible main, link paths and image alternatives. Run the HTML checker and fix its messages, then test the links and images in the browser.

Across several pages, keep the same repeated header, menu and footer. Give each page its own title and main heading, and adjust relative paths from its folder. Colors, fonts, spacing and columns can then be added through CSS without changing the roles you have already established.