Headings, lists, links and images

A page with a single paragraph is not much of a portfolio. In this lesson you will learn the building blocks of almost every web page: headings to organize, lists to enumerate, links to connect pages and images to show your work. You will also master file paths, the number one source of broken links and missing pictures.

Organize with headings

HTML offers six heading levels, from <h1> (the most important) to <h6>. Think of them as the outline of a book. There is typically a single h1 per page for the main subject, h2 for the major parts, and h3 for the subsections inside them.

<h1>Maya Carter</h1>
<h2>Projects</h2>
<h3>Street portraits</h3>
<h3>Botanical drawings</h3>
<h2>About me</h2>

Never choose a heading because of how big it looks. Size is a styling matter that CSS will handle. Choose it for its place in the hierarchy, and do not skip levels (an h2 followed directly by an h4). Screen reader users often jump from heading to heading to scan a page, so a clean outline is also an accessibility feature.

Paragraphs and text-level elements

Body text goes in <p> elements. Inside a paragraph, a few inline elements add meaning:

• <strong>: strong importance, usually displayed in bold.
• <em>: emphasis, usually displayed in italics; it changes the way a sentence is read aloud.
• <br>: a line break inside a paragraph, for addresses or verses.
• <blockquote>: a quotation set apart from the text.
• <code>: a fragment of computer code.

Use strong and em for meaning, not decoration. If you only want bold or italic for looks, you will use CSS.

Lists

An unordered list (ul) shows bullet points when the order does not matter. An ordered list (ol) numbers items when order matters, such as steps. In both cases each entry is an li element, and the li elements must be direct children of the list.

<h3>Equipment I use</h3>
<ul>
  <li>A compact camera</li>
  <li>A sketchbook</li>
  <li>A tripod</li>
</ul>

<h3>How a commission works</h3>
<ol>
  <li>You send me your idea.</li>
  <li>We agree on a quote.</li>
  <li>I deliver the final images.</li>
</ol>

Lists can be nested: put a new ul or ol inside an li, not between two li elements. Lists are also the standard way to write menus, as you will see shortly.

Links

The hyperlink is what makes the web a web. You create it with the a (anchor) element and its href attribute, which holds the destination.

<a href="https://developer.mozilla.org/en-US/">MDN Web Docs</a>
<a href="about.html">About me</a>
<a href="#contact">Jump to the contact section</a>
<a href="mailto:hello@example.org">Email me</a>

The first link goes to another site. The second goes to a file in your own project. The third is an anchor link: it jumps to the element of the same page that has id="contact". The fourth opens the visitor’s email program.

Write meaningful link text. “Read the case study” is understandable out of context, which matters for people who navigate by list of links. “Click here” is not.

Opening in a new tab

Adding target="_blank" opens the link in a new tab. Use it sparingly, because it takes control away from the visitor, and add rel="noopener" for safety on external links:

<a href="https://example.org" target="_blank" rel="noopener">Partner site</a>

Understanding paths: absolute and relative

A path tells the browser where to find a file. There are two families, and mixing them up is the cause of countless “it works on my computer” moments.

An absolute URL contains everything, including the protocol and domain: https://www.example.org/images/photo.jpg. It is required for other websites.

A relative path starts from the location of the current file. Imagine this project:

portfolio/
  index.html
  about.html
  projects/
    street-portraits.html
  images/
    maya.jpg
    street-01.jpg

From index.html:

• about.html points to the file in the same folder.
• projects/street-portraits.html goes down into a subfolder.
• images/maya.jpg goes down into the images folder.

From projects/street-portraits.html, to reach images/street-01.jpg you must first go up one level with ../:

<img src="../images/street-01.jpg" alt="...">
<a href="../index.html">Back to home</a>

A leading slash, as in /images/maya.jpg, means “from the root of the site”. It works once the site is on a server but often fails when you open files directly from your disk. For your own files, prefer simple relative paths.

Images

The void element img inserts an image. Two attributes are essential: src (where the file is) and alt (a text alternative).

<img src="images/street-01.jpg" alt="A cyclist crossing a rainy street at dusk" width="800" height="533">

The width and height attributes, given in pixels, tell the browser the image’s proportions before it loads. The page then keeps the right amount of space and does not jump around. You will make the image flexible with CSS later.

Writing good alternative text

The alt text is read aloud by screen readers, shown if the image fails to load, and used by search engines. Describe what matters in context, in a short sentence. If the image is purely decorative, use an empty attribute, alt="", so screen readers skip it. Do not write “image of…”: the software already announces an image.

Choosing an image format

We will come back to image size and optimization in the performance lesson.

Figures and captions

When an image comes with a caption, wrap them in figure and figcaption. The link between picture and caption is then explicit:

<figure>
  <img src="images/street-01.jpg" alt="A cyclist crossing a rainy street at dusk" width="800" height="533">
  <figcaption>Rainy evening, Lyon.</figcaption>
</figure>

A clickable image and a simple menu

Put an img inside an a to make an image clickable. And combine what you have learned to build a menu: a list of links.

<ul>
  <li><a href="index.html">Home</a></li>
  <li><a href="about.html">About</a></li>
  <li><a href="contact.html">Contact</a></li>
</ul>

Your turn

Extend your portfolio project.

1. Create about.html next to index.html, using the same skeleton.
2. On index.html, add an h2 “Projects” with a list of three project names, and an h2 “About me”.
3. Add a menu (list of links) to both pages, linking Home and About.
4. Add a photo of yours or any image you own to the images folder. Insert it in about.html in a figure with a caption and a useful alt.
5. Add a link on about.html that jumps back to the top of the page.

<ul>
  <li><a href="index.html">Home</a></li>
  <li><a href="about.html">About</a></li>
</ul>
<h1 id="top">About me</h1>
<figure>
  <img src="images/maya.jpg" alt="Maya holding a camera on a bridge" width="400" height="400">
  <figcaption>Me, on a photo walk.</figcaption>
</figure>
<p>I have been taking photographs for ten years.</p>
<p><a href="#top">Back to top</a></p>