Semantic HTML

Jekyll can generate valid-looking pages from terrible HTML.

The generator does not automatically make your structure meaningful.

Use elements for their job

Prefer meaningful structure:

<header>
<nav aria-label="Primary">
<main>
<article>
<section>
<footer>

Use headings to represent hierarchy, not font size.

Use links for navigation.

Use buttons for actions.

Jekyll makes semantics reusable

A good layout can enforce useful shared structure across every generated page.

A bad layout can repeat the same semantic mistake across every page.

That is architectural leverage in both directions.

Audit the generated output

Do not only inspect template source.

The accessibility target is the generated document.

Check:

• one <main> region;
• sensible heading order;
• navigation landmark;
• descriptive link text;
• image alt behavior;
• document language;
• meaningful title.

Failure example

A project-card include uses:

<div onclick="...">Open project</div>

It may look clickable.

It does not automatically carry the keyboard/semantic behavior of a link or button.

Choose the element that represents the actual action.

Portfolio action

Perform a semantic pass on your shared layout and one generated project page.

Checkpoint

List three semantic decisions your source templates make that affect every generated page.