Static Site Generators in the Age of AI

You have something worth sharing: notes from your work, an explanation you have written, a useful collection of resources, or a project you want others to understand. A website gives those materials a place where people can find and read them.

In this chapter, you will make the first small part of that website. You will open a local preview, change an introduction, and watch the page update. You will also make a deliberate mistake and repair it.

The first result is modest: a readable home page headed My Knowledge Notebook, with an introduction and links to two sections on the page. Across the book, this notebook will grow into a site with articles, projects, and resources. Later, you will ask an AI agent to help maintain it, review the agent's changes, and publish approved updates.

For now, success means being able to say: “I know which file contains these words, I can change them, and I can put them back.”

What you will be able to do

By the end of this chapter, you should be able to:

• Start and stop a local Hugo preview.
• Find the file containing the home-page introduction and edit it.
• Explain the roles of the content file, layout, and browser preview.
• Recover from a small editing mistake and preserve a working copy.

No previous HTML, CSS, Git, or programming experience is required. The starter includes a little code for you to copy. You are not expected to understand that code yet.

1.1 A quick picture of what we are building

Imagine a notebook whose pages can be displayed as a website. You write the words in ordinary text files. A layout supplies the page structure, and a stylesheet supplies its appearance. Hugo combines them into files a browser can display.

Hugo is a static site generator, often shortened to SSG. “Generate” means that it produces the website output from your source material. “Static” describes how that output can be served; it does not mean you can never update the site or add interaction.

For this first exercise, remember three roles:

Hugo's official quick-start guide demonstrates the same basic relationship between a project, its content, and its local preview. Our exercise uses a smaller embedded starter so this chapter can stand alone.

1.2 Get the tools ready

You need a desktop or laptop computer, a browser, a text editor, and Hugo. You can read the chapter on a phone, but the practical steps assume a computer.

A text editor saves the actual characters in a file. Use Visual Studio Code, or another editor you already know that saves plain text. A word processor is not suitable for these project files. VS Code is available from its official download page.

A terminal is a place where you enter commands. Each command below tells your computer to perform one action. Type the command and press Enter. Do not type the surrounding code fences or a prompt such as PS> or $.

For this chapter, you do not need a GitHub account, a domain name, or a paid AI subscription.

Install Hugo for your operating system

If Hugo is already installed, go directly to the verification command below.

Windows: Open PowerShell from the Start menu. If Windows Package Manager (winget) is available, the following installation command is listed in Hugo's documentation:

winget install Hugo.Hugo.Extended

Follow the installer prompts. Then close and reopen PowerShell. If you were using VS Code's terminal, restart VS Code as well so it can find the newly installed program. If winget is unavailable, use the prebuilt-binary instructions in the official Windows installation guide.

The command installs the extended edition. This chapter uses only core features and also works with the standard edition; there is no need to replace a working standard installation solely for this exercise.

macOS: If Homebrew is already installed, open Terminal and run:

brew install hugo

If Homebrew is not installed, follow the prebuilt-binary route or another supported route in the official macOS installation guide.

Linux: Follow the official Linux installation guide for your distribution. Check the installed version rather than assuming your distribution's package is recent enough for this exercise.

Check that Hugo can run

In your terminal, enter:

hugo version

You should see a line identifying Hugo and its version. Extra information about the edition, operating system, or build is normal. Record the version you installed in a separate learning note; it will help if you need to troubleshoot later.

This starter uses the template conventions introduced in Hugo 0.146.0. Its build and live-edit exercises were verified with Hugo 0.150.0 through 0.166.0. Use version 0.146.0 or later; older distribution packages (such as legacy packages from Debian/Ubuntu apt) do not support all.html and will fail to build. In Hugo 0.158.0 and later, site language configuration uses locale instead of languageCode to avoid deprecation warnings. See the template-system overview for the relevant changes.

1.3 Create your project folder

Using your normal file manager, create a folder named my-knowledge-site somewhere convenient, such as inside Documents.

Open VS Code and choose File → Open Folder, then select that folder. If your editor asks whether you trust the folder, remember that this is the new folder you just created for the exercise.

In the editor's file explorer, create these folders and files. Paths in this table are relative to my-knowledge-site.

The resulting paths are hugo.toml, content/_index.md, layouts/all.html, and static/css/site.css.

Pay attention to the underscore in _index.md. In Hugo, a leading underscore designates a section or branch bundle (such as the home page), whereas index.md without an underscore designates an individual standalone leaf article. Also make sure the files are not accidentally named hugo.toml.txt or all.html.txt. Creating them inside the code editor helps avoid hidden filename-extension problems.

You can either create these four files by hand or obtain them ready-made from the companion starter repository (ssg-playground, branch chapter-01).

Copy the contents from Starter files near the end of this chapter into the four matching files. Copy only what is inside each code block; do not include the backticks. Save every file.

The HTML and CSS are supplied materials. Leave them unchanged for now. We will examine their structure in later chapters. This small starter performs the presentation role that a larger theme would normally provide.

1.4 Open your first preview

In VS Code, choose Terminal → New Terminal. The integrated terminal normally opens in the project folder. Confirm that you are in the folder containing hugo.toml:

• In PowerShell, type Get-Location to show the folder and Get-ChildItem to list its contents.
• In macOS or Linux terminals, type pwd to show the folder and ls to list its contents.

If you are in the wrong place, close that terminal, open the correct project folder in the editor, and create a new terminal there.

Now run:

hugo server

Leave the terminal running. Read its output and find the local address, normally:

http://localhost:1313/

Enter that address in your browser's address bar (or hold Ctrl and click the link directly in the VS Code terminal, or Command on macOS). If Hugo reports a different address or port, use the one it reports.

You should see:

• The site name, My Knowledge Notebook, near the top.
• A navigation row with Home, My interests, and Next steps.
• The heading Welcome to my knowledge notebook.
• A short introduction and two sections underneath it.

The navigation links for My interests and Next steps move within this same page. We will add separate pages later.

This is a local preview. localhost refers to the computer you are using. Opening that address on somebody else's computer will not open your website. We will make the site publicly reachable in the publishing chapter.

Hugo's development server watches project files and normally rebuilds and refreshes the preview after changes. The terminal stays occupied while that server runs; this is expected behaviour. Hugo server documentation

1.5 Make the page yours

Open content/_index.md in the editor. Find this sentence:

Hello! I am Dana. This is where I collect useful ideas, learning notes, and small projects.

Dana is a fictional example. Replace the name and introduction with your own wording. For example:

Hello! I am Sara. I use this notebook to explain what I am learning and share useful resources.

Save the file with Ctrl+S on Windows/Linux or Command+S on macOS. Look at your browser. The introduction should change, while the colours and page layout remain the same.

If it does not change, refresh the browser once. Then check that you saved the correct file and that the terminal has not reported an error.

You have now completed the central operation you will repeat throughout the book:

Edit the source, save it, and inspect the result.

Change the heading as well

At the top of the same file, find:

title: "Welcome to my knowledge notebook"

Change only the text inside the quotation marks:

title: "Welcome to Sara's learning space"

Save and inspect the page again.

The lines between the two --- markers form the front matter in YAML format: a small block of structured metadata about the page. Here, its title supplies the large page heading. The writing below the second marker forms the page's main content.

You only need to recognise that distinction today. Chapter 2 develops Markdown, and Chapter 9 explains structured metadata and configuration in detail.

1.6 Understand what changed

You edited the writing without editing the layout. The starter keeps those responsibilities in separate files:

The name at the top of the site comes from hugo.toml. The larger heading inside the article comes from content/_index.md. They can be different because they describe different things: the whole site and the current page.

Hugo reads the project and generates the browser-facing output. Continue editing the source files listed above. If you later encounter a generated folder such as public, changes made there may be overwritten by another build.

You may notice expressions such as {{ .Title }} in the layout. They mark places where Hugo inserts information. You do not need to write template expressions yet; first become comfortable changing content and recognising its effect.

1.7 Practise recovering from a mistake

Before experimenting, save your current work. Then copy the introduction paragraph into a separate temporary note outside the project. This gives you a small, clear recovery reference.

In content/_index.md, replace the introduction paragraph with:

This paragraph was changed by mistake.

Save the file and inspect the preview. The website still works, but its content is wrong.

Return to the editor. Use Undo until your previous introduction returns, then save again. If the editor's undo history is unavailable, restore the paragraph from your temporary note and save it.

Check the browser to confirm the original introduction is back.

This distinction will matter when we introduce AI agents: a page can build successfully and still contain the wrong information. Seeing a successful build is one check; reading the result is another.

For this exercise, undo and a temporary copy are sufficient. The Git chapter will give you a more dependable record of changes and a way to restore earlier versions.

1.8 Where AI agents will fit

An AI agent can be given access to project files and asked to propose or perform a change. In later chapters, you will set up an agent and control the scope of its work. Today, consider this illustrative task:

This instruction identifies the file, the intended improvement, and the limits. If an agent invented a qualification or project, you would reject or correct that addition even if its wording sounded polished.

No agent installation is required for this chapter. You have already practised the human actions that make later agent work inspectable: locating the source, reading changes, previewing the page, and restoring earlier text.

1.9 Try a small independent change

Without changing the layout or stylesheet:

1. Add one interest under My interests, following the existing list format.
2. Rewrite the sentence under Next steps to describe something you want to share.
3. Save the file and verify both changes in the browser.

Keep the section headings unchanged for this exercise because the starter's navigation links point to them. We will learn how headings and links relate in the next chapter.

Now explain aloud, or in a learning note:

• Which file did you change?
• Which visible parts of the page changed?
• Why did the appearance remain consistent?

If you can answer those questions, you have begun to understand the workflow rather than merely repeat commands.

1.10 Stop, restart, and preserve your work

Click inside the terminal running Hugo and press Ctrl+C. This stops the preview server; it does not delete your files. On macOS, the terminal interruption is also Ctrl+C, not Command+C.

The browser may continue to show the last page it loaded. That does not mean the preview server is still running. Refreshing or navigating after stopping the server may show a connection error.

To resume, open the project folder and run:

hugo server

Open the reported address again.

For a simple end-of-chapter checkpoint, stop the server, save all files, and use your file manager to copy the entire my-knowledge-site folder to a sibling folder named my-knowledge-site-ch01-backup. Do not put the backup inside the active project. Continue working in the original folder in Chapter 2.

Completion check

• I can run hugo version and identify my installed version.
• I can open the local website preview.
• I can change the introduction and page title in content/_index.md.
• I can distinguish content, configuration, layout, and styling.
• I have restored an intentionally incorrect paragraph.
• I can stop and restart the preview.
• I have preserved a working copy of the project.

In Chapter 2, we will add a separate article and learn the Markdown needed to structure it, link it, and illustrate it.

Troubleshooting when you need it

When an error occurs, change one thing at a time and try again. Keep the error message: it provides useful evidence for troubleshooting and for later work with an agent.

Starter files

These four blocks contain the complete starter for this draft. Copy each into the file named above it. They are provided as project materials; studying HTML, CSS, and template syntax is deferred to later chapters.

File 1: hugo.toml

baseURL = 'https://example.org/'

locale = 'en'

title = 'My Knowledge Notebook'

https://example.org/ is a placeholder, not your published website. In Hugo v0.158.0+, locale = 'en' is the standard language configuration (older Hugo versions used languageCode = 'en'). Hugo's local server supplies the preview address. We will configure the real public address when publishing.

File 2: content/_index.md

---

title: "Welcome to my knowledge notebook"

---



Hello! I am Dana. This is where I collect useful ideas, learning notes, and small projects.



## My interests



- Learning new things

- Explaining useful ideas

- Sharing small projects



## Next steps



I will use this notebook to publish my first article and organise useful resources.

File 3: layouts/all.html

<!doctype html>

<html lang="en">

<head>

  <meta charset="utf-8">

  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>{{ .Title }} | {{ .Site.Title }}</title>

  <link rel="stylesheet" href="{{ "css/site.css" | relURL }}">

</head>

<body>

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

  <header>

    <p class="site-name">{{ .Site.Title }}</p>

    <nav aria-label="Main navigation">

      <a href="{{ "" | relURL }}">Home</a>

      <a href="{{ "" | relURL }}#my-interests">My interests</a>

      <a href="{{ "" | relURL }}#next-steps">Next steps</a>

    </nav>

  </header>

  <main id="main" tabindex="-1">

    <article>

      <h1>{{ .Title }}</h1>

      {{ .Content }}

    </article>

  </main>

  <footer>A place to learn, explain, and share.</footer>

</body>

</html>

File 4: static/css/site.css

* { box-sizing: border-box; }

body {

  margin: 0;

  background: #f5f3ed;

  color: #263238;

  font-family: system-ui, sans-serif;

  line-height: 1.7;

}

header, main, footer {

  width: min(100% - 2rem, 48rem);

  margin-inline: auto;

}

header { padding-block: 2rem 1rem; }

.site-name { font-size: 1.25rem; font-weight: 700; }

nav { display: flex; flex-wrap: wrap; gap: 1rem; }

a { color: #005b66; text-underline-offset: 0.2em; }

main {

  padding: clamp(1rem, 4vw, 2rem);

  background: #ffffff;

  border: 1px solid #d5d9d8;

  border-radius: 0.75rem;

  overflow-wrap: anywhere;

}

h1 { font-size: clamp(1.7rem, 5vw, 2.5rem); line-height: 1.2; }

h2 { margin-top: 2rem; line-height: 1.3; }

footer { padding-block: 1.5rem; }

a:focus-visible { outline: 3px solid #005b66; outline-offset: 4px; }

.skip-link { position: absolute; top: -10rem; left: 1rem; }

.skip-link:focus {

  top: 0.5rem;

  padding: 0.5rem 1rem;

  background: #ffffff;

}

The starter uses all.html as a general HTML layout, following Hugo's newer template conventions. It intentionally keeps presentation local and small; no external theme download, Git submodule, JavaScript package, or custom font is required for this exercise. Later chapters will develop the layout into reusable parts.

Editorial note for the author (remove before publication)

This is a self-contained chapter draft for review. To honour the request for one Markdown file, the starter is embedded in the chapter instead of referring to an unavailable companion download. This is a provisional adaptation of the blueprint's packaged starter-theme approach; it does not select a third-party theme for the whole book.

Before publication, choose whether to package this small starter or adapt the exercise to the final theme. A downloadable, versioned starter should make copying four files unnecessary in the main reading path; the embedded source can remain as a fallback. Supply matching screenshots from that final starter.

Documentation was consulted on 17 September 2026. The four starter blocks were extracted directly from this Markdown file and tested with Hugo 0.150.0, standard edition, on Linux amd64. The production build passed with warnings treated as failures. Checks confirmed the home-page content, navigation target IDs, and copied stylesheet. A running local server reflected a changed introduction, an intentional mistaken edit, and restoration of the corrected text. These checks verified server responses; they did not constitute a visual browser audit or a beginner usability trial.

Package-manager commands install the versions available from their respective repositories; they do not pin the final book's software baseline. Before publication, select a supported release baseline and rerun the exercises against it. A representative beginner trial, visual browser inspection, and Windows/macOS installation walkthroughs remain necessary before describing this chapter as publication-ready.

In Chapter 1, you changed a home page. Now you will give your website something more substantial to read: its first article.

The article will describe a small thing you have learned. You will give it sections, add links and a screenshot, and make it reachable from the home page. Along the way, you will learn the Markdown needed to make a piece of writing understandable both as a text file and as a web page.

Here, publish locally means making the article appear in the site you preview on your computer. You will not upload it to a public host in this chapter.

What you will be able to do

By the end, you should be able to:

• Create an article in its own folder and control whether it is a draft.
• Structure its text with headings, paragraphs, lists, emphasis, and code formatting.
• Add working links and an image with meaningful alternative text.
• Check the rendered article, repair a broken image reference, and make the article available in a normal local preview.

2.1 Start from your working website

Open the original my-knowledge-site project from Chapter 1. Keep your personalised introduction. Its relevant files are:

If you need to rebuild that starting point, Chapter 1 includes all four starter files, or you can switch to the chapter-01 branch in the companion ssg-playground repository. No new software, theme, or account is required here.

Open a terminal in the folder containing hugo.toml. If a preview server is still running, stop it with Ctrl+C. Then start it with one additional option:

hugo server -D

The -D option (short for --buildDrafts) tells Hugo to include pages marked as drafts. Leave this terminal running and open the address it reports, normally http://localhost:1313/.

You should see the home page you already know. We will keep using the same editor, project, and browser while adding one article.

2.2 Make an article before studying the syntax

Inside content, create a folder named articles. Inside it, create another folder named first-learning-note. In that folder, create a file named index.md.

Its complete path, relative to the project, is:

content/articles/first-learning-note/index.md

Copy this small article into that file and save it:

---

title: "My first learning note"

draft: true

---



Today I learned how to change a page in my knowledge notebook.



## What I tried



I edited my introduction, saved the file, and checked the local preview.



## What I learned



The words on the page come from a content file that I can edit.

Open the article directly in your browser:

http://localhost:1313/articles/first-learning-note/

Use your server's actual port if it differs from 1313. Include the final slash.

You should see the article title and two sections, inside the same styled layout as your home page. The title is supplied by the front matter; the body comes from the writing below it.

Your home page does not yet link to this article. That is expected. The Chapter 1 starter displays page content but does not automatically create an article directory. We will add an explicit link shortly and develop wider navigation in Chapter 3.

2.3 Understand the file you just created

The top of the file contains two pieces of metadata:

Keep true and false unquoted. They represent yes/no values rather than ordinary text. The quotation marks around the title enclose a text value.

Hugo supports several front-matter formats. We are using YAML between --- markers. For now, learn these two fields; you do not need a complete configuration-language lesson. Hugo front-matter documentation

Below the closing marker is the article body, written in Markdown. Markdown uses visible characters such as ## and - to describe structure. Hugo turns that structure into HTML for the browser.

Why this file is called index.md

The article has a folder of its own so its text and image can stay together. Hugo calls a folder containing index.md and associated resources a leaf page bundle. The home page uses _index.md, with an underscore, because it is a different kind of page. Preserve both filenames as shown. Hugo page bundles

The article's folder name supplies the last part of its address in this setup. Changing its displayed title does not change that folder name. Later configuration can alter URL behaviour; this is the default arrangement used by our starter.

2.4 Give the writing a clear structure

Continue editing the same article. Add one small feature at a time, save, and check the browser.

Paragraphs and headings

A blank line separates paragraphs:

I started with a short introduction.



Then I changed the words and checked the preview.

Pressing Enter once inside a paragraph usually does not create a new paragraph in the rendered page. Use a blank line when you mean to start a new thought.

In our layout, the front-matter title already becomes the main page heading. Start body sections with ##, and use ### for a subsection:

## What I tried



I changed the introduction on my home page.



### How I checked it



I saved the file and read the updated text in the browser.

Use heading levels to express the relationship between ideas. Do not choose ### just because you prefer a smaller font. Styling comes later.

Emphasis and short code references

Use a pair of double asterisks for a short piece of important text, and a pair of single asterisks for emphasis:

My rule is **change one thing at a time** and check it *before continuing*.

Use backticks around a filename or short command:

I edited `content/_index.md` and used `hugo server -D` to preview drafts.

The backticks make technical text easier to distinguish from the surrounding sentence. Displaying a command in an article does not execute it.

Lists

Use a bulleted list for related items:

- A content file contains my writing.

- A layout supplies the page structure.

- A stylesheet controls the appearance.

Use a numbered list when the order matters:

1. Change a sentence.

2. Save the file.

3. Inspect the preview.

Keep blank lines before and after these blocks. That makes the source easier to read and helps avoid accidental formatting interactions.

Hugo's Markdown support includes features beyond basic Markdown. Different publishing tools can support different extensions, so check rendered output when moving content between systems. Hugo content formats

2.5 Add a useful link

A Markdown link has readable text in square brackets and a destination in parentheses:

I can consult the [Hugo documentation](https://gohugo.io/documentation/) when I need help.

Add this sentence to your article, save, and click the rendered link. The text tells the reader what the destination contains. “Click here” would provide less context.

For a link back to this site's home page, add:

[Return to my home page](../../)

From /articles/first-learning-note/, the first ../ goes up to /articles/, and the second reaches the site's home location. These are web-address relationships, not instructions to browse folders on your computer.

This link is deliberately relative to the article's address. It also remains inside the site when the same folder structure is hosted under a prefix such as /my-knowledge-site/. Moving the article to a different depth would require reviewing the link. Later we will introduce Hugo's tools for managing links as sites grow.

Link to a section on the same page

Append this section to your article:

## My next step



I will write another short note about something I can explain clearly.

Near the article's opening paragraph, add:

[Jump to my next step](#my-next-step)

With this starter, Hugo automatically gives that heading the identifier my-next-step by converting the text to lowercase, replacing spaces with hyphens, and removing punctuation. Click the link and look at the browser address: it should end in #my-next-step. On a short page, the visual movement may be slight.

This also explains Chapter 1's navigation. Its My interests and Next steps links target specific home-page headings (#my-interests and #next-steps). Changing a heading can change its generated identifier, so check links that point to it.

2.6 Illustrate the article with your own screenshot

Open your site's home page. Use your operating system's screen-capture tool to capture just the relevant page area. Save the image as a PNG file named notebook-preview.png.

If the capture tool puts the image on the clipboard, paste it into a basic image editor and save or export it as PNG. Renaming a JPEG extension to .png does not convert its format. Use the tool's actual Save or Export option. (If using the companion ssg-playground repository on branch chapter-02, a sample image is already included beside the article).

Place the file next to the article:

content/articles/first-learning-note/notebook-preview.png

The screenshot is a reader-created asset, so this single chapter file needs no separate image download. Capture your own example site and avoid including unrelated tabs, notifications, or private material in the image.

Add the following to the article after the section explaining what you learned:

## My notebook in the browser



![The notebook home page showing its introduction, interests, and next steps](notebook-preview.png)



*My home page after editing the introduction. Screenshot by the author.*

Save and inspect the article. The exclamation mark makes this an image rather than a text link. The path names a file in the same page bundle. Do not write content/articles/... inside these parentheses: that is a source-file location, not the image's browser address.

The words inside the square brackets are alternative text. They describe the useful information in the image for someone who cannot see it. Adjust the wording if your screenshot shows something different. The italic sentence is a visible caption; it serves a different purpose from alternative text.

If you use another person's image in future, establish permission or an appropriate licence and retain the required attribution. Finding an image online does not by itself grant permission to republish it.

Keep the image within the page

Chapter 1's small stylesheet did not include image sizing or code block styling. Open static/css/site.css and add these rules at the end, outside its existing braces:

article img {

  display: block;

  max-width: 100%;

  height: auto;

  border-radius: 0.5rem;

  margin-block: 1rem;

}



article pre {

  max-width: 100%;

  overflow-x: auto;

  background: #eae8e1;

  padding: 0.75rem 1rem;

  border-radius: 0.5rem;

}

Save and refresh the preview. The first rule lets large images shrink to the available width while preserving their proportions. The second lets long code samples scroll within their own area with distinct background styling. Resize the browser to check the result. These are supplied styling adjustments; Chapter 5 will explain CSS properly.

2.7 Display a command without running it

Sometimes a learning note needs to show several lines exactly. A fenced code block begins and ends with three backticks. The word after the opening backticks identifies the content type.

Copy the following three-line sample into the body of your article:

```text

hugo server -D

```

Copy the inner three-backtick opening line, the command, and the closing line; the outer frame is only how this book displays the example. The article will show the command as a code sample. It will not start another server.

If all the writing after a code block appears as code, look for a missing closing fence. You can close a server terminal with Ctrl+C; closing a Markdown code block requires the matching backticks in the file. They solve different problems.

Optional: a small comparison table

If your note needs a simple comparison, try:

| Action | What I check |

| --- | --- |

| Edit a paragraph | The meaning is still correct. |

| Add a link | The intended page opens. |

| Add an image | It loads and has useful alternative text. |

The separator row is part of the syntax. Your current CSS may display the table with minimal styling. That is acceptable for this exercise: the goal is to recognise a structured comparison. Tables are optional here and are not required for the completed article.

2.8 Test and repair a broken image reference

Before changing anything, confirm that your image currently loads. Then temporarily change only the image filename in the Markdown:

![The notebook home page showing its introduction, interests, and next steps](notebook-preview-missing.png)

Save and refresh the article. The image should fail to load. Depending on your browser, you may see its alternative text or a broken-image indicator. Hugo may still report a successful build: the ordinary Markdown image reference in this starter does not guarantee that the destination exists.

Repair the reference:

1. Look inside the article folder and read the actual filename.
2. Restore notebook-preview.png in the Markdown, matching spelling and letter case.
3. Save and refresh the article.
4. Confirm that the image appears again.

You have practised checking the source against the output. Keep that habit when an AI agent proposes filenames or links. A plausible-looking reference is not evidence that its destination exists.

2.9 Make the article ready and link it from the home page

Read the article as a visitor would. Check its meaning, heading order, links, image, and alternative text. Replace the sample sentences with accurate statements about your own work where appropriate.

When it is ready, change this front-matter line:

draft: false

Save the file. In the terminal, stop the current server with Ctrl+C, then restart without the draft option:

hugo server

Open the article's address again. It should still appear. You have confirmed that the article no longer depends on a draft-inclusive preview.

If it disappears, check whether draft is still true in the correct file. Do not immediately add -D back and assume the issue is solved; that would hide the distinction you are trying to verify.

The draft field is a publishing control, not an access-control mechanism. The source remains readable to anyone with access to the project, and a draft-inclusive deployment would include the draft. Never use this flag to protect confidential writing.

Link the article from the home page

Open content/_index.md. Leave your introduction, interests, and Next steps section intact. Add this new section at the end of the body:

## Latest writing



- [My first learning note](articles/first-learning-note/)

Save, visit the home page, and click the new link. From the home page, articles/first-learning-note/ points to the article's published path. There is no content/ prefix and no index.md in the destination.

Now click the article's Return to my home page link. Also try the shared navigation at the top: Home opens the home page, while My interests and Next steps return to the corresponding home-page sections. They do not point to sections inside the article.

This modest manual link is enough for two pages. Do not worry if visiting /articles/ itself shows a heading without an article list; our starter has no automatic listing loop yet. We will improve organisation next and build reusable listings in the template chapters.

2.10 Try an independent variation and save your checkpoint

Make one more improvement to this article:

1. Add a subsection describing one difficulty you encountered and how you resolved it.
2. Include either a numbered procedure or a short code sample where it helps the explanation.
3. Check the article in the normal preview without -D.
4. Follow the home-page link and both article links again.

The new writing should report what actually happened. Do not turn an illustrative example into an invented personal experience.

If you already use a browser chatbot, an optional writing-only exercise is to ask it to suggest clearer headings for a paragraph you supply. Compare its suggestions with the original meaning before changing your file. An account or agent setup is not required for this chapter; direct project access comes later.

Explain the result to yourself

• Why does this article use index.md while the home page uses _index.md?
• What changes when you remove -D from the server command?
• Why does the image reference contain only its filename?
• Which link would need review if you moved the article deeper into the URL structure?

You should be able to answer using this project. Memorising every Markdown feature is unnecessary.

Save your Chapter 2 checkpoint

Stop the preview with Ctrl+C and save all edited files. Copy the project folder to a sibling folder named my-knowledge-site-ch02-backup, outside the active project. Continue working in the original folder in Chapter 3.

Your changes should be limited to:

The configuration and layout from Chapter 1 remain sufficient for this exercise. Generated files may also change when Hugo runs; they are output, not additional authoring tasks.

Completion check

• My article opens in the ordinary hugo server preview.
• Its front-matter title supplies the main heading, and body sections use appropriate heading levels.
• Its links open the intended destinations.
• The screenshot is beside index.md and displays correctly.
• Its alternative text describes what the screenshot actually shows.
• I repaired the intentionally broken image reference.
• The home page links to the article without replacing my earlier content.
• I have saved a working Chapter 2 checkpoint.

Chapter 3 will develop this two-page beginning into a clearer website structure, with pages, sections, and navigation chosen around the visitor's needs.

Troubleshooting when you need it

Completed article for comparison

The following is a complete reference version of content/articles/first-learning-note/index.md. It assumes your screenshot is saved beside it. Preserve your own accurate wording if you have personalised the exercise. Copy the content inside the outer four-backtick display block; retain the inner three-backtick code block as part of the article.

---

title: "My first learning note"

draft: false

---



Today I learned how to change a page in my knowledge notebook.



[Jump to my next step](#my-next-step)



## What I tried



I edited my introduction, saved the file, and checked the local preview.



### How I checked it



1. Change a sentence.

2. Save the file.

3. Inspect the preview.



## What I learned



The words on the page come from a content file that I can edit.



My rule is **change one thing at a time** and check it *before continuing*.



- A content file contains my writing.

- A layout supplies the page structure.

- A stylesheet controls the appearance.



I edited `content/_index.md`. To include drafts in the local preview, I used:



```text

hugo server -D

```



I can consult the [Hugo documentation](https://gohugo.io/documentation/) when I need help.



## My notebook in the browser



![The notebook home page showing its introduction, interests, and next steps](notebook-preview.png)



*My home page after editing the introduction. Screenshot by the author.*



## My next step



I will write another short note about something I can explain clearly.



[Return to my home page](../../)

Editorial note for the author (remove before publication)

This draft continues the exact four-file starter embedded in Chapter 1. It does not assume a third-party theme, an automated article listing, a content-generation archetype, a Git repository, or an installed AI agent. The shared layout already renders individual pages. The added CSS supports screenshots and code blocks without requiring a separate styling lesson.

The screenshot is deliberately created by the reader, allowing this deliverable to remain one Markdown file. A companion package should eventually provide a reusable example image and matching screenshots of the finished page. The complete reference article provides a recovery point; a packaged Chapter 1 checkpoint is still desirable for readers who need to restart the project.

The chapter teaches links relative to the rendered URL under the starter's existing configuration. Template helpers and content-aware link resolution should be introduced later without retroactively claiming that ordinary relative links automatically survive arbitrary moves. Repeat the subdirectory checks when the actual publishing workflow is introduced.

Validation on 17 September 2026 reconstructed the starter from the current saved Chapter 1 and extracted the article examples and CSS directly from this chapter. Hugo 0.150.0, standard edition, on Linux amd64 built the completed project with warnings treated as failures. Both domain-root and /my-knowledge-site/ base URLs passed checks for local links, heading targets, stylesheet paths, and the image resource. Checks also confirmed one main heading, rendered emphasis, and the image's alternative text.

Separate builds confirmed draft exclusion without -D and inclusion with it. A running local server served the draft article and image, returned 404 for the intentionally broken image path, and served the repaired image. Restarting without -D after setting draft: false retained the article. A small generated PNG was used only as a path-resolution test fixture; it was not a screenshot and is not part of the deliverable. Actual screenshot capture, visual browser review, cross-platform walkthroughs, and a representative beginner trial remain unverified and are required before publication.

Your website now has a home page and an article. You know how to edit both, but a new visitor does not know where your files are. They need clear routes through the information you have published.

In this chapter, you will add an About page, give Articles a useful landing page, introduce a Projects section, and collect a few resources. Then you will replace the small home-page navigation with links that work across the website.

The aim is a site whose organisation makes sense to someone who has never seen your project folder. Every destination we add will contain something useful, even if it is only a short explanation and one carefully chosen link.

What you will be able to do

By the end, you should be able to:

• Choose pages and section names around a visitor's needs.
• Distinguish an individual page from a section landing page and use the appropriate index filename.
• Connect the home page, sections, and individual items with working links and shared navigation.
• Check a visitor's route through the site and recover from a change that breaks an address.

3.1 Start with the website you already have

Continue in the original my-knowledge-site folder. Your Chapter 2 article should be marked draft: false, have its screenshot beside it, and be linked from the home page.

The files we depend on are:

If you need to rebuild that starting point, switch to the chapter-02 branch in the companion ssg-playground repository, or review the Chapter 2 completed files.

Open a terminal in the folder containing hugo.toml:

hugo server

Open the address reported in the terminal, normally http://localhost:1313/. Follow the Latest writing link and confirm the article still works. Return to the home page.

We will use normal, non-draft pages for the short examples in this chapter. They are local practice content and must be reviewed before any later public deployment. No new installation is needed.

3.2 Add an About page first

A new visitor may want to know what your notebook is for. Give them a short answer.

Inside content, create an about folder and a file named index.md inside it. Its path is content/about/index.md.

Copy this complete file, then replace the introduction with accurate wording about yourself or your work:

---

title: "About this notebook"

draft: false

---



This notebook collects things I am learning and projects I am developing.



## What you can find here



I write short explanations, describe small projects, and collect resources that help me learn.



## Where to begin



Read [my first learning note](../articles/first-learning-note/) for an example of how I record what I have tried.

Save and open:

http://localhost:1313/about/

Use your actual server port if it is different. Check the title, read the text, and follow the link to the article.

You have added a new destination using skills from Chapter 2. It does not need a new stylesheet or a new HTML layout.

3.3 Decide what belongs where

Before adding more folders, write a short answer to these questions in a learning note outside the project:

1. Who is this website primarily for?
2. What should that person be able to find or do?
3. Which existing content answers those needs?

For our example, the primary visitor is a fellow learner who wants to understand an idea, inspect a small project, or find a useful reference. That gives us a manageable structure:

These names are a starting point, not a universal formula. A course website might use Lessons and Exercises; a research group might use Research and Publications. Choose words your intended visitors recognise.

Avoid adding a menu item simply because you might write something for it later. A smaller site with useful destinations is easier to understand than a large collection of empty pages.

The organisation of information and the routes connecting it are often called information architecture. At this scale, the table above is enough planning. You do not need a complex diagram to begin.

3.4 Make Articles a useful landing page

Your article already exists under content/articles/. In Chapter 2, visiting /articles/ did not show an article list because our minimal layout has no listing loop.

We can make that address useful with ordinary Markdown. Create content/articles/_index.md. Notice the underscore: this file describes the section that contains articles, rather than a single article at the end of the structure.

Use this complete content:

---

title: "Articles"

draft: false

---



Short notes about ideas I have tried and things I am learning.



## Start reading



- [My first learning note](first-learning-note/): Editing a page, checking the result, and recording what changed.

Save and open:

http://localhost:1313/articles/

The page now explains what the section contains and provides a link to the article. Click it.

Hugo recognises top-level content directories as sections. Adding _index.md gives this section its own title and introductory content. Hugo also supports nested sections, but we will keep our structure shallow. Hugo sections

The list you just wrote is manual. Adding another article file will not automatically add a bullet here. For now, maintain the list yourself. The template chapters will show how to generate such lists from content.

Keep the two index filenames distinct

Do not rename the section's _index.md to index.md. A leaf bundle built around index.md has different rules for the files beneath it; the two names are not interchangeable. Hugo page-bundle documentation

3.5 Add Projects and a Resources page

The website itself is a small project you are developing. You can describe its purpose and current state without claiming that it is finished.

Create a projects folder inside content. Then create the two files below.

Section page: content/projects/_index.md

---

title: "Projects"

draft: false

---



Small projects I am developing, with notes about their purpose and progress.



## Current work



- [My knowledge notebook](learning-notebook/): A website for organising explanations, project notes, and useful resources.

Project page: content/projects/learning-notebook/index.md

---

title: "My knowledge notebook"

draft: false

---



## Purpose



I am building a small website where readers can find my learning notes and follow my projects.



## Current status



This is a work in progress. I have a home page and an article, and I am improving the site's organisation.



## What I have learned



I can edit Markdown, preview a page, and check links and images.



Read [my first learning note](../../articles/first-learning-note/) for an example.



[Back to Projects](../)

Create the learning-notebook folder before saving its index.md. Save both files, open /projects/, follow its project link, and use Back to Projects to return.

The project description is intentionally short. Change any sentence that does not match what you have actually done. A statement such as “work in progress” helps readers interpret the page accurately.

Avoid making a copy of the first article inside Projects. The article explains an experience; the project page describes the wider work and links to that experience. Keeping one article avoids maintaining two copies of the same text.

A small Resources page

For the moment, Resources can be one page containing a few references. It does not need a section full of individual resource pages.

Create content/resources/index.md:

---

title: "Resources"

draft: false

---



References that support the work recorded in this notebook.



## Website publishing



- [Hugo documentation](https://gohugo.io/documentation/): The official reference for Hugo configuration, content, and templates.

- [Hugo page bundles](https://gohugo.io/content-management/page-bundles/): An explanation of grouping a page with related resources.



## Examples from this notebook



- [My first learning note](../articles/first-learning-note/): A practical record of editing and checking content.

- [My knowledge notebook project](../projects/learning-notebook/): The purpose and current state of this website.

Save and open /resources/. Follow each link. The external links leave your site; the internal examples stay within it.

The explanation after each link tells the visitor why it is included. That is more useful than collecting many unexplained URLs. When maintaining a resource list, keep links you have checked and can describe accurately.

3.6 Add navigation and clear starting points

The navigation supplied in Chapter 1 links to Home and two headings on the home page. Our site now needs routes to its main destinations.

Open layouts/all.html. Find the existing block beginning with <nav aria-label="Main navigation"> and ending with </nav>.

Replace that block only with:

<nav aria-label="Main navigation">

  <a href="{{ "" | relURL }}">Home</a>

  <a href="{{ "about/" | relURL }}">About</a>

  <a href="{{ "articles/" | relURL }}">Articles</a>

  <a href="{{ "projects/" | relURL }}">Projects</a>

  <a href="{{ "resources/" | relURL }}">Resources</a>

</nav>

Save the file and refresh the preview. The new navigation should appear on the home page, article, and new pages because they all use the shared layout.

Do not replace the whole layout with this fragment. Keep the surrounding document, the stylesheet link, the Skip to content link, the main content area, and the footer.

You need only recognise two things today: the words between the link tags are the visible labels, and the quoted paths inside the template expressions identify the destinations. relURL makes those links relative to the configured site base, including a hosting subdirectory. The paths supplied to it here deliberately have no leading slash. Hugo relative-URL function

We will explain the HTML in Chapter 4 and the template expressions in the later templating chapters. This supplied replacement is a small, controlled change rather than a requirement to learn the full template language now.

Three distinct things that work together

Hugo has a menu system that can separate navigation data from its rendering. We will use more structured approaches when we have enough template knowledge. For this exercise, the five explicit links make the relationship visible and easy to inspect. Hugo menus

The My interests and Next steps sections can stay on your home page. We are removing their top-navigation entries, not deleting the content or changing its existing heading identifiers.

Give the home page clear starting points

A visitor may scan the body of the home page before noticing its navigation. Help them choose a useful next step.

In content/_index.md, preserve your existing introduction, My interests, Next steps, and Latest writing. Add this section at the end:

## Explore the notebook



- [About](about/): What this notebook is for.

- [Articles](articles/): Explanations and learning notes.

- [Projects](projects/): Work in progress and what I have learned from it.

- [Resources](resources/): References and useful examples.

Save and inspect the home page. These links repeat some navigation destinations, but add context. They do not copy the destination pages' full content.

A home page should help people begin. As the site grows, you can shorten the introduction or select a smaller set of featured items if the page becomes crowded. You do not need to show every future article on the home page.

3.7 Choose stable names, addresses, and organising tools

Use short, descriptive folder names. The examples use lowercase letters and hyphens: first-learning-note and learning-notebook. This is a practical convention for our English-language project, not a rule that all websites must use English URLs.

Avoid names such as page2, new-final, or test-copy for destinations you intend to keep. They say little to a visitor and become confusing as the site grows.

Here is the completed map. Preview paths are relative to the local site address.

Our Markdown links are relative to the page where they appear. For example, learning-notebook/ works from the Projects landing page, while ../projects/learning-notebook/ works from Resources. Copying a relative link to a page at another location can change what it points to.

A displayed title and a URL can change independently

In content/about/index.md, change the title from “About this notebook” to “Why I keep this notebook”. Save and reopen /about/.

The page heading changes, but the address remains /about/ in our current configuration. The navigation still says About because its label was written separately in the layout. Restore the original title or keep the new one if it suits your writing.

Renaming a content folder is different: in this project it changes the corresponding URL. Once a site has public readers, existing bookmarks and inbound links matter. Later chapters will cover redirects and planned migrations.

Sections, tags, and categories: different organising tools

Sections answer “where does this item belong in the site?” Tags and categories can describe subjects shared by content in different locations.

For our growing notebook:

Hugo calls such subject groupings taxonomies. Categories and tags are conventional names; Hugo does not force categories to be broad or tags to be narrow. That distinction is an editorial convention we would adopt and document. Hugo taxonomies

We will configure and display these labels in later content-modelling and template exercises. Simply adding a tags field does not make our current minimal layout display tag badges or useful linked lists. For this chapter, sections and explicit links are sufficient.

Resist creating a label for every word in an article. Before introducing a grouping, decide how it will help a visitor find related material and who will keep its names consistent.

3.8 Find and repair a broken route

This exercise is for your local practice copy. Do not perform unplanned moves on a public site.

First open /projects/ and confirm that My knowledge notebook opens the correct project page. Then:

1. Stop the preview server with Ctrl+C.
2. In the editor, rename the folder content/projects/learning-notebook to content/projects/learning-notebook-test. Keep its index.md inside it.
3. Leave the links in the Projects and Resources pages unchanged.
4. Restart hugo server, open /projects/, and click its project link.

The link still points to the old address, so a freshly generated preview should no longer find the project there. Open /projects/learning-notebook-test/ directly to confirm that the page exists at its new address.

The content has not been deleted. Its destination has moved while the links have stayed the same. Hugo can build successfully even when a manually written link no longer reaches a page.

If the old page remains visible, your browser may be serving a cached copy of the earlier page. Perform a hard refresh (Ctrl+Shift+R on Windows/Linux or Cmd+Shift+R on macOS), or restart Hugo with --renderToMemory to guarantee that no stale disk files are served:

hugo server --renderToMemory

For this exercise, recover by restoring the original destination:

1. Stop the server.
2. Rename the folder back to learning-notebook.
3. Restart the normal hugo server preview.
4. Test the project links from both Projects and Resources.

We deliberately keep the original address. If a real move were needed, we would identify all affected links and consider redirects as part of the change.

3.9 Test the site as a visitor

Open a new browser tab at the home page. Follow each route below using links rather than typing every destination:

Use the keyboard for one route as well. Press Tab to move through links, observe the visible focus indicator supplied by the stylesheet, and press Enter on the link you want. The first link should offer Skip to content. It remains useful even though we changed the main navigation.

Resize the browser to a narrow window. The existing navigation styling should let its links wrap rather than forcing a single long row. Check this in your actual browser; an automated build cannot establish that the site is comfortable to use.

If a route is confusing, change its label or explanation before adding more content. An accessible destination is not necessarily an understandable one.

3.10 Try an independent improvement and preserve the result

Choose one of these small tasks:

• Add a second resource you have read, explain its relevance, and test its link.
• Improve the About page so it names a specific audience and explains what they can expect.
• Add one accurate sentence to the project page describing its next planned improvement, clearly distinguishing planned work from completed work.

Do not create new sections for this exercise. Practise making the existing structure more useful.

An optional AI-assisted planning task is to supply the visitor questions and current navigation labels to a chatbot and ask it to identify one confusing label. Ask for reasons, not a redesigned website. Decide whether the suggestion matches your intended audience before editing anything. Agent installation and direct file access still come later.

Explain in a learning note:

1. Why does Articles have _index.md while About has index.md?
2. Why did one navigation edit affect several pages?
3. Why does creating a new page not automatically add a link to our manual lists?
4. Why is changing a title usually a smaller routing change than renaming a folder in this setup?

Preserve the completed structure

Save your files and stop the preview. Copy the active project to a sibling folder named my-knowledge-site-ch03-backup. Keep it outside the project and continue using the original folder for Chapter 4.

The required changes are:

Your existing article, screenshot, configuration, and stylesheet remain in place. If you chose an independent improvement, its content may differ from the examples; its links should still work.

Completion check

• Every main navigation item opens a useful page in the normal preview.
• Articles and Projects have working landing pages.
• The original article still uses its Chapter 2 address and displays its image.
• My manual lists link to the correct items.
• I have distinguished site structure, navigation, and subject labels.
• I restored the original project folder name after the recovery exercise.
• I followed the visitor routes, including one with the keyboard.
• I saved a working Chapter 3 checkpoint.

Chapter 4 will inspect the HTML generated by these pages. We will connect the content you write, the navigation fragment you replaced, and the structure the browser actually receives.

Troubleshooting when you need it

You have written articles, created sections, and changed the navigation of your website. Now we will look at what the browser receives when it displays those pages.

The title on the screen is not simply large text. The navigation is not merely a row of coloured words. They have a structure that the browser can interpret. Understanding that structure will help you make deliberate changes, diagnose mistakes, and assess code suggested by an AI agent.

You will begin by inspecting your existing article. Then you will make a temporary browser-only change, update the site's footer in its source file, and investigate how a link can look correct while pointing to the wrong place.

What you will be able to do

By the end, you should be able to:

• Inspect a rendered page and recognise its main HTML elements and attributes.
• Distinguish Markdown, Hugo templates, generated HTML, and the browser's live document.
• Make and verify a small persistent change to the shared layout.
• Check headings, links, images, and the skip-link target for basic structural correctness.

You do not need to memorise an HTML reference or learn JavaScript in this chapter. We will work mostly with structures already present in your site.

4.1 Inspect the article and change it in the browser only

Start from the Chapter 3 project, with its seven authored pages and five navigation links (or checkout companion branch chapter-03 in ssg-playground). Keep your Chapter 3 backup outside the active project.

In the project terminal, run:

hugo server

Open the address reported by Hugo. Use Articles to reach your first learning note, normally at:

http://localhost:1313/articles/first-learning-note/

In a desktop browser, right-click the article's main heading and choose Inspect or Inspect Element, or press F12 (or Ctrl + Shift + I on Windows/Linux, Cmd + Option + I on macOS). If you are using a trackpad, use its context-menu gesture. Browser developer tools should open beside or below the page.

Look for the Elements panel in Chromium-based browsers such as Chrome or Edge, or the Inspector in Firefox. The exact interface varies. You can also open developer tools through the browser's menu and use its element-picker tool to select the heading. MDN: browser developer tools

You should find something like:

<h1>My first learning note</h1>

If you personalised the title, your words will differ. The important part is the surrounding h1 element.

Now inspect the first paragraph. You should find a p element containing its text. Inspect a section heading such as What I tried and look for h2.

You are already reading HTML by matching visible page content to the structure that displays it.

Make a change that does not touch your files

In the Elements or Inspector panel, find the text inside the article's h1. Double-click the text, if your browser supports that, and change it to:

This is a temporary browser edit

Press Enter. If direct text editing is unavailable, right-click the element in the panel, choose Edit as HTML, and change only its text. Preserve the opening <h1> and closing </h1> tags.

The visible heading should change. Now reload the page without editing or saving any project file.

The original heading should return. In an ordinary developer-tools session, this edit changes the browser's current document only. It does not update your Markdown file or Hugo template. This exercise assumes you have not configured developer-tool workspaces or persistent local overrides.

This is a useful way to try an idea, but a persistent correction belongs in the appropriate project file. Keep this distinction in mind when someone demonstrates a change using only browser tools.

4.2 Read the pieces of an HTML element

HTML stands for HyperText Markup Language. Its elements describe the structure and meaning of a document.

Consider an ordinary link:

<a href="https://gohugo.io/documentation/">Hugo documentation</a>

Elements can be nested. Close inner elements before their enclosing elements:

<p>Please <strong>check the link</strong> before publishing.</p>

Use straight quotation marks around attribute values. Keep spaces between attributes. Indentation makes relationships easier to read but does not create those relationships; the markup does.

Some elements, such as img, meta, and link, are void elements and have no closing tag in HTML. Do not add </img> after an image. MDN: basic HTML syntax

A link's text should help readers predict its destination. A working address paired with a misleading label is still a poor link. MDN: anchor element

4.3 Make one persistent HTML change

We will improve the footer so it includes a route to the About page. Because the footer belongs to the shared layout, the change should appear across the site.

Open layouts/all.html in your editor. Near the end, find:

<footer>A place to learn, explain, and share.</footer>

Replace that entire footer element, and only that element, with:

<footer>

  <p>Learn, review &amp; share.</p>

  <p class="footer-note">

    Read <a href="{{ "about/" | relURL }}">about this notebook</a>.

  </p>

</footer>

Save, then check the home page and the first article. Scroll to the bottom. Both should display the new footer. Its About link should open /about/ in this local setup. Reload the page: the change should remain because you saved it in the source layout.

The paragraphs sit inside footer; the link sits inside the second paragraph. That is nesting in a real project change.

The character reference & produces a visible ampersand, &. For literal angle brackets in ordinary HTML text, < and > represent < and >. When writing code examples in Markdown, continue using code fences rather than manually converting all their characters.

The footer-note class does not introduce a new visual style by itself. We will use it as a convenient styling target in Chapter 5.

Why there are braces inside the link

The source contains:

<a href="{{ "about/" | relURL }}">about this notebook</a>

The browser should receive a completed link, normally:

<a href="/about/">about this notebook</a>

The expression inside {{ ... }} is processed by Hugo before the browser receives the page. It adjusts the URL for the site's configured base. It is not browser-side HTML syntax. Keep this supplied expression intact; its full explanation belongs in the templating chapters. Hugo relative-URL function

4.4 Follow the journey from content to browser

The same article appears in several forms. Each has a different role:

The browser's live document is called the Document Object Model, or DOM. The browser constructs it by parsing HTML. Scripts or developer tools can subsequently change it.

If your browser offers View Page Source, open it for the local article and search for its title. This view exposes the HTML response rather than your Hugo template. The Elements panel shows the browser's parsed, live document; it can differ after edits or browser corrections. You may also see development-only code added for Hugo's live reload.

For everyday authoring, make persistent changes in your content or layout source. Editing a generated public/.../index.html file is unreliable because another build can overwrite it.

If the screen literally displays {{ .Title }}, check that you opened the Hugo preview address rather than double-clicking layouts/all.html in the file manager. A browser cannot execute Hugo template expressions.

Recognise the structure already in your layout

Read layouts/all.html from top to bottom. You do not need to change it again yet.

The head element is different from header. The former holds document information; the latter can provide introductory content within the body. Likewise, a document's title and its visible h1 serve different roles even when their wording overlaps.

Within this site's body, you will find:

These are semantic elements: their names communicate purpose. section can group a thematic part of a document, typically with a heading; aside can hold related supplementary content. Neither is needed just to make a coloured box. Choose markup for its role, then use CSS for appearance. MDN: structuring documents

The English language declaration fits our current example. It is not a rule for all pages in the future bilingual site. We will revisit language and direction together in the multilingual chapter.

4.5 Connect Markdown to the HTML it creates

Return to your article's Markdown file and compare it with the browser inspector:

Inspect one example from each of three rows. You are not expected to rewrite the article in HTML. The value of this comparison is knowing what your authoring choices produce.

Heading level is a structural choice

Our layout supplies one main h1 per page. Body sections use h2; their subsections use h3. This is our straightforward page structure, not a claim that font size determines importance.

Replacing an h2 with a bold paragraph may preserve a similar appearance but removes a section heading from the document structure. Screen-reader users can use heading navigation, so that difference matters. Conversely, making text an h2 only to enlarge it gives the document a misleading structure. MDN: heading elements

If you find two large article titles, inspect them and trace each back to its source. A common cause in our project is adding # My first learning note to the Markdown body when the layout already renders the front-matter title. Remove the unnecessary body title rather than hiding it with CSS.

4.6 Read attributes without guessing

Attributes add information to elements. Three groups matter immediately in this project.

Destinations and image descriptions

Inspect the screenshot in your first article. Its HTML should contain an image source and alternative text, similar to:

<img src="notebook-preview.png"

     alt="The notebook home page showing its introduction, interests, and next steps">

src identifies the resource. alt supplies a text alternative appropriate to the image's purpose. The visible italic caption you added in Chapter 2 is separate from alt.

An informative image needs useful alternative text; a purely decorative image may appropriately have alt="". Omitting the attribute is different from deliberately giving an empty alternative. Check the meaning in context instead of automatically describing every image the same way. MDN: image element

Identifiers and classes

An id identifies one element within a page. Its value should be unique in that document. The same value can appear on different pages: each page has its own document. A fragment such as #main can point to an element with id="main". MDN: id attribute

A class assigns a reusable label. Multiple elements may share the same class, and an element can have more than one class. CSS and scripts can use these labels to select elements. A class name does not itself create styling. MDN: class attribute

In our site, class="site-name" already has a stylesheet rule, while the new class="footer-note" has no specific rule yet. Neither needs to be globally unique.

Existing accessibility-related attributes

The navigation's aria-label="Main navigation" supplies an accessible name for that navigation region. Our main element has tabindex="-1", which makes it focusable without adding it as an ordinary stop in sequential Tab navigation. This supports the skip-link arrangement in the starter.

Keep these attributes while making unrelated edits. Use native HTML elements appropriately and understand the purpose of any accessibility attribute you add. Adding attributes at random is not an accessibility review.

4.7 Trace and repair the skip link

The first link in the layout is:

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

Its destination is the existing element:

<main id="main" tabindex="-1">

Together, they offer a route past repeated navigation to the page's content. The stylesheet keeps the link out of view until it receives focus.

Reload the home page and place keyboard focus in the page. Press Tab from the beginning of the page's focus order until Skip to content appears. Browser chrome can receive focus first; keep track of where focus is rather than assuming the first keypress always reaches the page. Activate the link with Enter. The address should acquire #main, and the browser should move to the main-content target. You may need a longer page to notice much scrolling.

Now make a deliberate source mistake. In layouts/all.html, change only the skip link's destination from #main to #missing-main. Do not change the main element's identifier. Save and reload.

The link still looks like a link. Its activation may add #missing-main to the address, but no element with that identifier exists. Hugo may build successfully because a successful template render does not prove that every fragment has a matching target.

Use the inspector's search facility to look for id="missing-main". Compare the result with id="main". Repair the source link by restoring href="#main", save, and repeat the keyboard check.

The lesson is specific: matching words in the address bar are not enough. Verify that the target exists and that the route is useful.

4.8 Know which source file to edit

When something looks wrong, first decide where the information came from:

Do not put the same paragraph into both the Markdown body and the shared layout. The layout would then repeat it across unrelated pages. Do not move page-specific writing into the layout just because the browser inspector made it look like one continuous HTML file.

Raw HTML embedded in Markdown also depends on the generator's rendering configuration. For this chapter, put the footer HTML in the supplied layout and keep ordinary page writing in Markdown. There is no need to change raw-HTML rendering settings.

4.9 Optional recognition: tables and form controls

You will encounter more HTML in later chapters and in agent-generated proposals. Recognise the purpose of these examples; do not add them to the project for this exercise.

A small data table

<table>

  <caption>Notebook content</caption>

  <thead>

    <tr><th scope="col">Section</th><th scope="col">Purpose</th></tr>

  </thead>

  <tbody>

    <tr><td>Articles</td><td>Learning notes</td></tr>

    <tr><td>Projects</td><td>Descriptions of ongoing work</td></tr>

  </tbody>

</table>

tr identifies a row; th a header cell; td a data cell. The caption identifies the table, and scope="col" associates each header with its column. Tables are useful for tabular information, not for positioning the page's navigation and content. MDN: table element

A labelled input

<label for="contact-email">Email address</label>

<input id="contact-email" name="email" type="email">

The label's for value matches the input's id. The name can identify the value when form data is submitted; it serves a different purpose from id. A placeholder is not a substitute for a persistent label. MDN: label element

This fragment is not a working contact system. An actual form needs a deliberate submission route and processing arrangement. Its HTML alone does not deliver messages, store records, or establish that submitted information is safe. We will build a complete modest integration in the interaction chapter. MDN: form element

4.10 Judge an agent's proposed change, then make your own

Consider these two illustrative proposals. No agent account is needed.

Ask an agent to explain which files and elements it intends to change and why. Compare that explanation with the rendered result. A confident description does not replace inspecting the markup or checking keyboard behaviour.

For an optional writing exercise, describe how you would request the footer change we made: identify the file, the existing block, the required wording, the About destination, and what must remain intact. We will turn instructions like this into practical agent tasks later.

Make one independent change and preserve it

Change only the first paragraph of your new footer to a short sentence that fits your notebook. Preserve the About link, the footer-note class, and the rest of the layout. If you use an ampersand in HTML text, practise writing it as &.

Then:

1. Check the footer on Home, About, and your first article.
2. Activate its About link from the article.
3. Reload and confirm the source change persists.
4. Confirm the repaired skip link still targets main.

Save all files, stop the preview, and copy the project to a sibling folder named my-knowledge-site-ch04-backup. Continue using the original project for Chapter 5.

Only layouts/all.html needs a permanent change in this chapter. The temporary inspector edit does not belong in any file. The intentionally broken skip-link destination must be repaired before creating the checkpoint.

Completion check

• I can locate the article's h1, a body heading, a link, and its image in the inspector.
• I can explain why a temporary browser edit disappears on reload.
• I can recognise elements, attributes, nesting, and void elements.
• I can distinguish the page's Markdown from its shared layout and generated HTML.
• My updated footer appears across the site and its link works.
• The skip link and main-content identifier match again.
• I know which source file to inspect for common content and layout problems.
• I saved a working Chapter 4 checkpoint.

Chapter 5 will use CSS to change appearance deliberately. The footer-note class, browser inspector, and structural distinctions you learned here will give those styling changes a clear foundation.

Troubleshooting when you need it

Completed layout for comparison

Use this as a recovery reference for layouts/all.html if an edit went wrong. It preserves Chapter 3's navigation and includes the new footer. Retain your own accurate footer wording if you completed the independent exercise.

<!doctype html>

<html lang="en">

<head>

  <meta charset="utf-8">

  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>{{ .Title }} | {{ .Site.Title }}</title>

  <link rel="stylesheet" href="{{ "css/site.css" | relURL }}">

</head>

<body>

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

  <header>

    <p class="site-name">{{ .Site.Title }}</p>

    <nav aria-label="Main navigation">

      <a href="{{ "" | relURL }}">Home</a>

      <a href="{{ "about/" | relURL }}">About</a>

      <a href="{{ "articles/" | relURL }}">Articles</a>

      <a href="{{ "projects/" | relURL }}">Projects</a>

      <a href="{{ "resources/" | relURL }}">Resources</a>

    </nav>

  </header>

  <main id="main" tabindex="-1">

    <article>

      <h1>{{ .Title }}</h1>

      {{ .Content }}

    </article>

  </main>

  <footer>

    <p>Learn, review &amp; share.</p>

    <p class="footer-note">

      Read <a href="{{ "about/" | relURL }}">about this notebook</a>.

    </p>

  </footer>

</body>

</html>

Your notebook already has a readable layout. In Chapter 4, you inspected its HTML and added a footer note. Now you will give that note a style and make two small adjustments to the reading experience.

The visible result is small but deliberate: the footer note sits below a thin rule in quieter text, body text reads a little larger, and your article's section headings have clearer space above them. Everything else should look as it did at the end of Chapter 4.

Our aim is modest: understand enough CSS to customise this Hugo website and check an agent's proposed changes. You do not need to learn every property, build a design system, or become a professional web designer. Work through the three edits, learn how to inspect their effects, and keep the reference material for when you need it.

What you will be able to do

By the end, you should be able to:

• Find the stylesheet used by this Hugo project and explain how pages load it.
• Read a simple CSS rule and change text size, spacing, or a border deliberately.
• Recognise the existing rules that help the site fit smaller screens.
• Diagnose a selector mistake and check the result across pages and screen widths.

Start with the working Chapter 4 project (or checkout companion branch chapter-04 in ssg-playground). Its footer should contain the paragraph with class="footer-note", and its skip link should be repaired. Keep your Chapter 4 backup outside the active project.

The only source file we will change is static/css/site.css. No new software or account is required.

5.1 Give the footer note a style

Run the preview from your project terminal:

hugo server

Open the address Hugo reports and scroll to the footer. In your editor, open static/css/site.css. Add this rule at the end of the file, after the final closing brace:

.footer-note {

  margin-top: 0.75rem;

  padding-top: 0.75rem;

  border-top: 1px solid #c5ccce;

  color: #46545b;

}

Save and return to the browser. Reload if necessary. You should see a fine line above the About note, space around that line, and a slightly softer colour for its ordinary text. The link keeps its existing link colour and underline.

Check the footer on Home and your first article. The same change should appear on both, because both pages use the same stylesheet and footer markup.

You have made your first targeted CSS change. Before adding anything else, understand how it found the right paragraph.

Read the rule you just added

CSS stands for Cascading Style Sheets. It describes the presentation of HTML elements.

In this rule, .footer-note is the selector: it selects elements whose class list includes footer-note. The dot belongs to the CSS selector; it is not part of the HTML class name.

The declarations inside the braces follow the pattern property: value;. For example, color: #46545b; sets a text colour. Use a colon between the property and value, and a semicolon to end each declaration. MDN: getting started with CSS

Compare the two files without changing the HTML:

<p class="footer-note">

.footer-note {

  color: #46545b;

}

The second snippet illustrates the connection; do not add a second rule just to copy it.

5.2 Know where CSS belongs in this Hugo project

Our starter uses a deliberately simple arrangement:

Hugo copies files from static/ into the published site. In our default configuration, static/css/site.css becomes css/site.css within the output. The word static does not appear in its public URL. Hugo also supports an assets/ directory for resources used through its asset-processing features; we do not need that workflow here. Hugo: directory structure

Our layout already includes:

<link rel="stylesheet" href="{{ "css/site.css" | relURL }}">

Keep that line intact. On the local preview at the site root, it normally produces a link to /css/site.css. All seven authored pages load the same CSS file. Hugo supplies the files and resolved address; the browser applies the CSS.

To see what the browser receives, open /css/site.css on the same preview address, for example http://localhost:1313/css/site.css when Hugo is using that address. You should see the stylesheet text, including your new rule. Return to the page afterwards.

Edit the source under static/, not the generated copy under public/. A build can replace the latter. Putting CSS into the article's Markdown body will not update the shared stylesheet.

Other Hugo themes may provide a custom-CSS setting or use an asset pipeline. Follow that theme's documented extension mechanism if you later adopt one. The filename and directory arrangement in this chapter belong to our starter; they are not a universal theme customisation recipe.

5.3 Learn only the selectors you meet here

You can understand most of our stylesheet with these examples:

The space in article img describes a relationship. The commas in header, main, footer group separate selectors. Keep that distinction when reading an agent's suggestion.

Why the link did not take the footer's colour

Many text properties, including colour and font family, are inherited from a parent when the element has no applicable value of its own. The footer paragraph gets our new colour. Its link already has a colour from the starter's a rule, so it does not simply inherit the paragraph's colour.

When declarations compete on the same element and property, CSS uses the cascade. In our plain stylesheet, a class selector normally outweighs an element selector for otherwise comparable normal declarations. Between equally specific, otherwise comparable rules, the later declaration wins. “The last rule always wins” is therefore an unreliable shortcut. MDN: handling CSS conflicts

For now, inspect the relevant element and look for the property in the Styles or Rules panel. Overridden declarations are commonly crossed out. The Computed panel shows the resolved value. You do not need to calculate every possible specificity case.

Keep edits in the existing rule where practical. Adding repeated overrides or !important without understanding the competing rule makes a small stylesheet harder to maintain.

5.4 Make article text comfortable to read

Find the existing body rule. Add one declaration immediately after font-family:

font-size: 1.125rem;

The complete rule should now be:

body {

  margin: 0;

  background: #f5f3ed;

  color: #263238;

  font-family: system-ui, sans-serif;

  font-size: 1.125rem;

  line-height: 1.7;

}

Replace or edit the original rule; do not append this entire block as a second body rule.

Save and read a paragraph in your first article. With a root font size of 16 CSS pixels, 1.125rem is 18 CSS pixels. Browser settings may give a different result: rem refers to the root element's font size, not to a guaranteed physical size. Text that has its own font-size rule, such as our main heading, will retain that separate sizing. MDN: font-size

Our existing system-ui, sans-serif font stack asks for a system interface font and provides a generic fallback. It avoids needing a font download for this exercise. The existing unitless line-height: 1.7 makes line spacing respond to the text size.

Try reading several sentences, not just the title. Is the text comfortable? Are navigation labels still usable? This value is a starting choice for our notebook, not a rule that all websites must use.

Three units worth recognising

Keep the existing clamp(...) expressions for now. They already limit our heading size and content padding while allowing them to vary with the viewport. You need to recognise their purpose before you need to write them from memory.

5.5 Adjust spacing without changing the content

Find the existing h2 rule and change margin-top from 2rem to 2.5rem:

h2 {

  margin-top: 2.5rem;

  line-height: 1.3;

}

Save and compare two sections of the first article. The extra separation should help reveal where a new section begins. You did not add blank paragraphs or change the heading level.

Inspect a heading and look for the browser's box-model display. Its labels help distinguish three ideas:

The footer exercise uses all three: its margin separates it from nearby content, its border provides a dividing line, and its padding separates that line from its text. Vertical margins between ordinary blocks can collapse rather than simply add together, so use the inspector when measured gaps surprise you.

Our starter begins with * { box-sizing: border-box; }. This makes specified box widths include padding and borders, which helps avoid accidentally making a box wider than intended. You can retain it without studying alternative box models now. MDN: the box model

5.6 Understand the responsive behaviour already supplied

A content website needs to remain readable when the available width changes. Our starter already includes several useful rules. Leave them in place and observe what they do.

A reading area with a maximum width

header, main, footer {

  width: min(100% - 2rem, 48rem);

  margin-inline: auto;

}

In this page, the width is the smaller of the available width minus 2rem and 48rem. This provides side space on narrow screens and prevents the reading area expanding indefinitely on wide ones. margin-inline: auto centres these blocks in our current layout.

Avoid replacing this with a large fixed width simply to match one screenshot. Resize the preview and watch the content width change.

Navigation that can wrap

nav {

  display: flex;

  flex-wrap: wrap;

  gap: 1rem;

}

The starter uses Flexbox to arrange the links. flex-wrap: wrap allows them to continue onto another line when there is not enough room. gap separates the items and wrapped lines. This small use of Flexbox is sufficient for our navigation; a full Flexbox course is unnecessary here. MDN: flex-wrap

Images and code that fit the article

Chapter 2 supplied:

article img {

  display: block;

  max-width: 100%;

  height: auto;

}



article pre {

  max-width: 100%;

  overflow-x: auto;

}

Keep these rules. The image can shrink to fit the article while retaining its proportions. Long preformatted code can scroll within its own area instead of forcing the whole page wider. These rules do not reduce the image file's download size.

A media query applies rules when a condition, such as viewport width, is met. You may encounter one in a theme, but our current changes do not need a new breakpoint. Flexible sizing and wrapping already address this chapter's layout needs. MDN: responsive design

Check the result at more than one size

Check Home, your first article, and Resources. Narrow the browser window or use its responsive device preview (toggle with Ctrl + Shift + M on Windows/Linux or Cmd + Shift + M on macOS) at about 360 CSS pixels wide, then try a wider view. Also increase browser zoom to 200% and check that you can still reach and read the content; return to your usual zoom afterwards.

Look for clipped words, links that overlap, distorted images, and page-wide sideways scrolling. Navigation wrapping is expected. A long code block scrolling within its own box is different from the entire page requiring horizontal scrolling.

A responsive preview is a useful check, but it does not reproduce every physical device. When available, inspect the site on an actual phone as well.

5.7 Diagnose one small mistake

Temporarily change the selector of your new rule from .footer-note to .footer_note, using an underscore. Leave its declarations and the HTML unchanged. Save and reload.

The line and new paragraph colour should disappear. The rule is valid CSS, but it no longer selects the paragraph. Hugo may report no error: it copies this stylesheet without checking whether its selectors match your intended HTML.

Inspect the paragraph and compare its class with the stylesheet selector character by character. The expected rule will not appear among its matching rules. Restore .footer-note, save, and confirm that the styling returns.

Use this short sequence when a change seems to do nothing:

1. Check the file. Did you save static/css/site.css in the project being previewed? Does the served CSS contain the edit?
2. Check the match. Does the selector describe the intended element? Is the class spelling exact?
3. Check the declaration. Are the property, colon, value, semicolon, and braces correct? Is another rule overriding it?

Temporary developer-tools edits are useful experiments, but normally disappear on reload. Save the intended correction in your source stylesheet.

5.8 Finish with a small independent decision

Choose a heading gap that suits your article. Change only h2's margin-top to 2rem, 2.25rem, or 2.5rem. Keep the value you find easiest to read, and explain why in one sentence.

Check the footer, headings, and navigation on the three pages used above. Then use Tab to move through links. Keep the existing visible focus outline and the working Skip to content link. The a:focus-visible rule helps keyboard users locate their current link; removing it for a cleaner screenshot would make the site harder to use. MDN: :focus-visible

For this exercise, retain our text and background colours, and retain link underlines. Future palette changes should include a contrast check; visual preference alone does not establish readability. Standard accessibility guidelines (WCAG AA) require a contrast ratio of at least 4.5:1 for normal body text and 3:1 for large text. Modern browser developer tools display this ratio automatically in their color picker.

When reviewing an agent's styling proposal, ask three questions: which selector changes, which pages it affects, and how the result behaves at a narrow width. For example, “Add space above article section headings by editing the existing h2 rule in static/css/site.css; preserve heading levels and check the article on a narrow screen” is a bounded task you can assess.

Save your Chapter 5 checkpoint

Save your files, stop the preview, and copy the project to a sibling folder named my-knowledge-site-ch05-backup. Continue working in the original project.

Completion check

• I can find the editable stylesheet and its served URL.
• I can read a selector and a property: value; declaration.
• My footer note has its intended border, spacing, and text colour.
• I adjusted body text and heading spacing in the existing rules.
• I repaired the deliberate selector mistake.
• I checked several pages at narrow and wide widths and with increased zoom.
• Links remain recognisable and keyboard focus remains visible.
• I saved a working Chapter 5 checkpoint.

This is enough CSS for our next steps. Grid layouts, animation, complex selectors, preprocessors, utility frameworks, and comprehensive theme design are outside this chapter's scope. Look up additional features when a concrete site requirement calls for them.

Chapter 6 introduces Git so that you can record changes, compare versions, and recover work more reliably than by copying whole project folders.

Troubleshooting when you need it

Completed stylesheet for comparison

This is a recovery reference for static/css/site.css, including the earlier starter rules. It reflects the guided values; retain your chosen heading gap if you completed the independent exercise. You do not need to memorise or retype this entire file.

* { box-sizing: border-box; }



body {

  margin: 0;

  background: #f5f3ed;

  color: #263238;

  font-family: system-ui, sans-serif;

  font-size: 1.125rem;

  line-height: 1.7;

}



header, main, footer {

  width: min(100% - 2rem, 48rem);

  margin-inline: auto;

}



header { padding-block: 2rem 1rem; }

.site-name { font-size: 1.25rem; font-weight: 700; }

nav { display: flex; flex-wrap: wrap; gap: 1rem; }

a { color: #005b66; text-underline-offset: 0.2em; }



main {

  padding: clamp(1rem, 4vw, 2rem);

  background: #ffffff;

  border: 1px solid #d5d9d8;

  border-radius: 0.75rem;

  overflow-wrap: anywhere;

}



h1 { font-size: clamp(1.7rem, 5vw, 2.5rem); line-height: 1.2; }

h2 { margin-top: 2.5rem; line-height: 1.3; }

footer { padding-block: 1.5rem; }



a:focus-visible { outline: 3px solid #005b66; outline-offset: 4px; }

.skip-link { position: absolute; top: -10rem; left: 1rem; }

.skip-link:focus {

  top: 0.5rem;

  padding: 0.5rem 1rem;

  background: #ffffff;

}



article img {

  display: block;

  max-width: 100%;

  height: auto;

}



article pre {

  max-width: 100%;

  overflow-x: auto;

}



.footer-note {

  margin-top: 0.75rem;

  padding-top: 0.75rem;

  border-top: 1px solid #c5ccce;

  color: #46545b;

}

In the previous chapters, you kept copies of the project before continuing. Those copies helped you recover, but comparing them becomes awkward. Which one contains the footer improvement? What changed in the stylesheet? Can you recover a file without replacing the whole site?

Git gives your project a history of recorded checkpoints. In this chapter, you will record your working Hugo site, save one useful content change, and recover from a deliberately poor styling change.

We will learn a small local workflow. You do not need a GitHub account yet. Branching strategies, merge conflicts, and advanced history editing can wait until there is a practical reason to use them.

What you will be able to do

By the end, you should be able to:

• Record the site's source files in a local Git repository while excluding generated output.
• Inspect changes, select them for a commit, and record a meaningful checkpoint.
• Distinguish removing a change from the next commit from discarding a file edit.
• Find recent checkpoints and restore a deliberately changed file.

Start with the working Chapter 5 project and keep its existing backup (or switch to companion branch chapter-05 in ssg-playground). Save all open files. Stop the Hugo preview for the initial setup so that the terminal is available for the commands below.

6.1 Prepare Git in the right folder

Open a terminal in the project folder that contains hugo.toml, content, layouts, and static. In an editor with an integrated terminal, opening the project folder first usually makes this straightforward. Check the terminal's location; opening a file in the editor does not necessarily change it. (If you are following along in the ssg-playground companion repository, it is already a Git repository—you can simply switch between chapter branches without re-running git init).

Run:

git --version

If Git is available, you will see a version number. If the command is not recognised, use the official Git installation page and follow the instructions for your operating system. Reopen the terminal afterwards and repeat the check. Installing Git and creating a GitHub account are separate tasks.

The examples in this draft were tested with Git 2.51.1. Use a recent supported installation rather than trying to match that exact version. Commands below are entered one line at a time and work in a normal PowerShell, macOS, or Linux terminal with Git installed.

Before creating a repository, run:

git rev-parse --show-toplevel

For the plain project created in this book, an error containing not a git repository is expected at this point. It means no enclosing repository was found.

If a path appears instead, Git already manages this folder or a parent folder. Do not create a nested repository blindly. If the path is this project, use its existing history and skip git init. If it is an unrelated parent, put the standalone Hugo project outside that repository before following this beginner setup.

Create the local repository

For our project without an existing repository, run:

git init -b main

This creates the repository's metadata and names the initial branch main. A branch names a line of development; we will use just this one for now. Git stores its local history in the project's .git directory. Leave that directory under Git's management. Git: init

No checkpoint has been recorded yet, and nothing has been uploaded.

Choose the author identity for your commits

Replace both placeholders before running:

git config user.name "Your Chosen Author Name"

git config user.email "[email protected]"

These settings apply to this repository because we have not used --global. They identify the author of future commits; they do not sign you into a service. Check them with:

git config user.name

git config user.email

The chosen name and email become part of commit history, which may later be shared. Use an identity you intend to share. If you already use GitHub and prefer its private commit address, copy the exact noreply address from your account settings. Do not invent one. Changing your setting later does not rewrite old commits. Git: first-time setup, GitHub: commit email addresses

6.2 Save the working site as your first checkpoint

Tell Git which generated files to leave out

Create a plain-text file named .gitignore beside hugo.toml. Include the initial dot and ensure your editor does not add .txt to its name. If the file already exists, retain its contents and add any missing rules below.

# Hugo output and generated files

/public/

/resources/

/.hugo_build.lock

/hugo_stats.json



# Local operating-system metadata

.DS_Store

Thumbs.db

For our starter, these Hugo outputs can be recreated. We want the source content, layouts, CSS, configuration, and article image in history. The /resources/ entry refers to the generated directory at the repository root; it does not exclude our content/resources/ page.

Ignore rules normally keep matching untracked files out of staging. They do not erase files or stop tracking something already committed. This list is tailored to the book's project, not every possible Hugo build arrangement. Git: gitignore

Select and inspect the initial files

Run:

git status

Before the first commit, the source files appear as untracked: present on disk but not yet recorded by Git. Generated directories covered by .gitignore should not appear in the ordinary list.

Select the book's source files:

git add .gitignore hugo.toml content layouts static

This prepares their current contents in Git's staging area, also called the index. Staging chooses what the next commit will contain. It is separate from saving a file in your editor. Git: add

Review that selection:

git status

git diff --cached --stat

git diff --cached

The status should now describe changes to be committed. The short summary lists files and change counts; the full diff shows text being added. An image normally appears as a binary change rather than readable lines. If Git opens a scrolling viewer, use Space to move forward and q to return to the prompt.

Check that the expected source files are present, including content/resources/index.md, and that generated public/ files and backup folders are absent. Review the content too: an API key or private note should not enter history just because it sits inside an otherwise useful directory.

If the selection contains something unexpected, correct it before committing. The remainder of this chapter assumes the ordinary book project shown above.

Record the checkpoint

Run:

git commit -m "Save Hugo site after Chapter 5"

git status

A commit records the staged project state with an identifier, author information, and a message. The -m option supplies that message directly. The command should report a new commit, and status should report a clean working tree when no other changes remain. Git: commit

A clean working tree describes Git's tracked state; it does not certify that the website is correct. Ignored files can still exist, and the browser checks from Chapter 5 still matter.

6.3 Understand the three places an edit can be

Before the next exercise, distinguish these:

Saving in the editor updates the working file. git add stages its current contents. git commit records the staged state.

If you stage a file and then edit it again, the additional edit is not automatically included. Stage it again if it belongs in the same commit, then review the staged diff. This is why a file can appear in both the staged and unstaged sections of git status.

For this chapter, make one small change at a time. That makes the distinction easier to see and the resulting history easier to read.

6.4 Record a useful content change

Open content/articles/first-learning-note/index.md. Add this section at the end, with a blank line before the heading:

## My publishing checklist



- Read the page in the local preview.

- Check its links and image description.

- Review the changed files before recording a checkpoint.

Save. Start hugo server in another terminal if convenient, or run it in the same terminal and stop it after inspecting the article. Check that the section appears correctly. A Git diff will help review the writing, but the preview reveals how it renders.

Back at an available terminal in the project root, run:

git status

git diff -- content/articles/first-learning-note/index.md

The file should be modified but not staged. The diff should show the new section with + prefixes. Removed text uses -; unchanged context helps locate the edit. The prefixes are part of the comparison display, not extra Markdown to copy.

Without --cached, this diff compares the working file with its staged version. With --cached, it compares the staged version with the last commit. The -- separates options from the file path. Git: diff

Stage and review:

git add content/articles/first-learning-note/index.md

git diff --cached -- content/articles/first-learning-note/index.md

Now run the unstaged comparison again:

git diff -- content/articles/first-learning-note/index.md

It should print nothing if you made no further edits after staging. Your change has not vanished: it is in the staged comparison.

Practise taking a file out of the next commit

Before committing, run:

git restore --staged -- content/articles/first-learning-note/index.md

git status

Open the Markdown file. Your publishing checklist should still be there. The command removed the change from the staging area while preserving the working file. Status should show it as an unstaged modification.

Stage it again and record it:

git add content/articles/first-learning-note/index.md

git diff --cached -- content/articles/first-learning-note/index.md

git commit -m "Add a publishing checklist to the first learning note"

git status

Use messages that explain the purpose of a change. “Add a publishing checklist” is more useful when browsing history than “update” or “stuff”. A single commit should represent a change you can describe coherently.

6.5 Recover from a deliberately poor CSS edit

First run git status. Begin this exercise only when your working tree is clean. This keeps unrelated work out of the recovery example.

Open static/css/site.css. In the body rule, temporarily replace:

font-size: 1.125rem;

with:

font-size: 6rem;

Save and inspect the article in Hugo's preview. Much of the inherited text should become impractically large. The page may still build successfully; the problem is the styling decision.

Do not stage or commit this deliberate mistake. Inspect it:

git diff -- static/css/site.css

Confirm that the only edit to this file is the font-size experiment. Then discard that working-file edit:

git restore -- static/css/site.css

This command overwrites that file's unstaged changes with its staged version. Because we began clean and never staged the experiment, that version is also the last committed one. It discards all unstaged changes in the named file, not just the font-size line. Git: restore

Check the file, reload the preview if needed, and run:

git status

The text size should be restored and the working tree clean. The committed publishing checklist remains in the article.

Two similar commands with different effects

These examples concern a file already in the first commit. If you accidentally staged the CSS mistake, plain git restore will not undo that staged version. In this exercise, unstage the stylesheet first using the first form, review its remaining diff, and then use the second form to discard the experiment.

For a file containing both useful work and a mistake, correct the unwanted line in your editor instead of restoring the whole file. The path-specific recovery above is appropriate because we deliberately isolated one unwanted edit.

6.6 Read the history you have created

Run:

git log --oneline -5

For a new repository following this chapter, you should see two commits, newest first: the publishing checklist and the Chapter 5 baseline. Each begins with an abbreviated identifier. Your identifiers will differ from anyone else's. Git: log

You can inspect the latest committed change to the article with:

git diff HEAD~1 HEAD -- content/articles/first-learning-note/index.md

Here, HEAD identifies the current commit and HEAD~1 its first parent, the preceding checkpoint in our simple history. This comparison should show the checklist addition. It requires the two commits we have just made.

Your record starts when you begin committing. Git has not reconstructed the individual steps from Chapters 1–5; they are represented together by the baseline commit. It also cannot reliably recover arbitrary edits that were never recorded.

Keep ordinary device backups. Local Git history lives on the same computer as the files and does not protect against losing that computer. If you copy the repository as a backup, include its .git directory so the history travels with it. Chapter 7 will add a remote copy on GitHub and the first publishing workflow.

6.7 Make your own small commit

Improve one sentence in content/about/index.md. Preserve its front matter and links. Then complete this cycle without copying a whole project folder:

1. Save and inspect the About page in the local preview.
2. Use git status and a file-specific git diff to review your change.
3. Stage the About file and inspect its staged diff.
4. Commit with a message explaining the improvement.
5. Check that status is clean and the new commit appears in the recent log.

If you forget the syntax, use the command card below. Understanding which state you are inspecting matters more than memorising options.

This is also the foundation for later agent work. Start from a known checkpoint, give the agent a bounded task, inspect every changed file, and decide what to record. A commit documents a change; it does not establish that AI-generated text is accurate or that the website behaves correctly.

Completion check

• Git manages the Hugo project folder I intended.
• The initial commit contains the site's source and required image, with generated output excluded.
• I can distinguish saving, staging, and committing.
• I reviewed and committed the article's publishing checklist.
• I unstaged a change without deleting the working edit.
• I discarded the isolated CSS experiment and checked the restored result.
• I made an independent About-page commit and can find it in the log.
• My working tree is clean, and I understand that the site is still local.

Your latest commit is the Chapter 6 checkpoint. Keep the earlier backup, but you no longer need a new sibling folder for every small revision.

This is enough Git for our next steps. Branching, merge conflicts, remote collaboration, and history editing are outside this chapter's scope. Learn each one when a concrete need appears rather than in advance.

Chapter 7 gives the project a public address. You will send this history to GitHub and let a supplied workflow build and publish the site from it.

Troubleshooting when you need it

Branching, collaboration, and undoing changes already shared with others require additional decisions. We will introduce them where needed. For now, the useful habit is to preview, review, stage, and commit a small understandable change.

Command card: the local workflow

Run commands from the repository root. Replace example paths where necessary.

Your website now has content, a readable layout, and a local Git history. This chapter gives it an address other people can visit.

You will put the existing repository on GitHub, let GitHub Actions build it with Hugo, and publish the result through GitHub Pages. Then you will make one small update and follow it from your editor to the live page.

This is our first publishing workflow. We will use a supplied configuration and explain its important parts. You do not need to learn all of GitHub Actions, YAML, or website hosting before your site can go online.

What you will be able to do

By the end, you should be able to:

• Connect your local Git repository to an empty GitHub repository and push your commits.
• Configure the site's public address and use a supplied Hugo publishing workflow.
• Find a deployment's status and verify the published pages, links, and image.
• Publish a reviewed content update and recognise where to investigate a failure.

Start with the completed Chapter 6 project (or switch to companion branch chapter-06 in ssg-playground). Its current branch should be main, its changes should be committed, and its local preview should work. The deliberate CSS mistake must already be repaired.

You need internet access, a GitHub account, and permission to create a repository in that account. We will also install GitHub CLI for browser-based sign-in from the terminal. The route below uses a public repository, GitHub-hosted standard runners, and the supplied github.io address. GitHub Pages is available for public repositories on GitHub Free; service limits still apply. No paid domain is needed for this exercise. GitHub: about Pages

A public repository exposes its committed source and history, including commit author details. Review what you recorded in Chapter 6 before uploading it. A Hugo page marked draft: true can be absent from the rendered site while its Markdown remains visible in a public repository.

7.1 Give the project a home on GitHub

Sign in to GitHub in your browser, or create an account and complete the required account setup. Create a new repository with these choices:

We need an empty remote repository because your local project already has its own commits. A licence is a separate publishing decision you can make deliberately later; a public repository does not by itself grant a general licence to reuse all its contents.

After creation, GitHub should show setup instructions for the empty repository. Keep that page open. Copy its HTTPS repository URL, which should have this shape:

https://github.com/YOUR-USERNAME/my-knowledge-site.git

YOUR-USERNAME is a placeholder. Use the account name from the repository URL, not your profile's display name. If that repository name is already in use, choose an unused name and substitute it consistently throughout the chapter.

Sign in from the terminal

Install GitHub CLI using the instructions for your operating system on the official GitHub CLI site. Reopen your terminal if necessary, then check:

gh --version

gh is GitHub CLI. It supplements the git commands you learned earlier.

Run:

gh auth login --hostname github.com --git-protocol https --web --scopes workflow

Follow the displayed instructions to open the browser, enter the device code if requested, and authorise GitHub CLI for your account. The additional workflow scope allows uploading the Actions workflow file we will add below. Complete any account verification there. Then run:

gh auth setup-git

gh auth status

These commands connect Git's authentication to your GitHub CLI sign-in and let you check which account is active. Your Chapter 6 commit email is author metadata; it is not a login credential. This route does not require putting a password or token into your project files. GitHub CLI: login, GitHub CLI: configure Git authentication

Connect and push the existing repository

In the terminal at your Hugo project root, run:

git status

git branch --show-current

git remote -v

The book project should be clean, on main, with no remote listed yet. If origin already exists, inspect its address before proceeding; do not replace an existing connection just to match the example. The workflow below assumes the main branch created in Chapter 6.

Replace the placeholder URL with the one copied from your empty repository:

git remote add origin https://github.com/YOUR-USERNAME/my-knowledge-site.git

git push -u origin main

A remote is a named connection to another repository. origin is our name for this one. The push transfers your committed history; -u sets the upstream relationship so later git push commands know where to send this branch. Unsaved or uncommitted edits are not included. Git: push

Refresh the repository page. You should see hugo.toml, the source folders, and your earlier commits. You should not need to upload public/ or drag individual files into GitHub's browser editor.

7.2 Distinguish the source address from the website address

For the project repository we just created, the addresses normally have these forms:

This chapter uses a project site, so the repository name appears in the website's path. A repository named exactly YOUR-USERNAME.github.io follows a different convention; do not rename our project to that special name for this exercise.

Git stores versions. GitHub hosts the shared repository. GitHub Actions runs the build instructions. GitHub Pages serves the generated website. These services work together, but pushing source files is not itself proof of a successful deployment.

In your repository's browser interface, open Settings → Pages. Under Build and deployment, set Source to GitHub Actions. Interface labels may move over time; the important choice is a custom Actions workflow rather than publishing directly from a branch folder. GitHub: custom Pages workflows

7.3 Set the public address in Hugo

Open hugo.toml. Replace only its baseURL value, using your actual username and repository name:

baseURL = 'https://YOUR-USERNAME.github.io/my-knowledge-site/'

Keep the final slash. Preserve the existing site title and language settings. (Note: in modern Hugo v0.158.0+, languageCode is deprecated in favor of locale = 'en'. If your build warns about languageCode, remove it and use locale = 'en' so that --panicOnWarning does not abort on the deprecation warning).

The repository path matters. A site published below /my-knowledge-site/ needs navigation and stylesheet addresses that include that prefix where appropriate. Our shared layout already uses Hugo's relURL function for those links. The article's relative image and content links were also designed for the existing folder structure.

Preview with:

hugo server

Open the full address reported by Hugo. With the configured project path, the preview may now be under /my-knowledge-site/ rather than at the local server's root. Check Home, Articles, the first article, and its image. Stop the preview with Ctrl+C when finished.

Then run an ordinary build:

hugo --minify --panicOnWarning

--minify reduces generated output where supported. --panicOnWarning makes warnings fail this build, so they receive attention before publication. Hugo writes the result to public/, which stays excluded from Git by the earlier ignore rule.

The workflow will obtain the actual Pages base address from GitHub and pass it to Hugo at build time. Keeping hugo.toml accurate also makes local builds useful. If you later rename the repository or add a domain, revisit the configuration and links together.

7.4 Add the supplied publishing workflow

Using your editor, create a folder named .github at the project root, a workflows folder inside it, and a file named hugo.yaml inside that:

.github/workflows/hugo.yaml

Paste the following complete file. Use spaces for indentation, and do not include the Markdown fence markers. You do not need to replace anything inside this workflow for the personal project repository described here.

name: Publish Hugo site



on:

  push:

    branches: [main]

  workflow_dispatch:



permissions:

  contents: read

  pages: write

  id-token: write



concurrency:

  group: pages

  cancel-in-progress: false



jobs:

  build:

    runs-on: ubuntu-24.04

    env:

      HUGO_VERSION: "0.150.0"

    steps:

      - name: Check out the source

        uses: actions/checkout@v7



      - name: Read the Pages configuration

        id: pages

        uses: actions/configure-pages@v6



      - name: Install Hugo

        shell: bash

        run: |

          curl --fail --location --retry 3 \

            --output "$RUNNER_TEMP/hugo.tar.gz" \

            "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"

          mkdir -p "$RUNNER_TEMP/hugo-bin"

          tar -xzf "$RUNNER_TEMP/hugo.tar.gz" -C "$RUNNER_TEMP/hugo-bin" hugo

          echo "$RUNNER_TEMP/hugo-bin" >> "$GITHUB_PATH"



      - name: Build the website

        env:

          PAGES_BASE_URL: ${{ steps.pages.outputs.base_url }}

        run: hugo --minify --panicOnWarning --baseURL "${PAGES_BASE_URL}/"



      - name: Upload the generated website

        uses: actions/upload-pages-artifact@v5

        with:

          path: public



  deploy:

    needs: build

    runs-on: ubuntu-24.04

    environment:

      name: github-pages

      url: ${{ steps.deployment.outputs.page_url }}

    steps:

      - name: Publish to GitHub Pages

        id: deployment

        uses: actions/deploy-pages@v5

The workflow uses GitHub's checkout and Pages actions, following the build-and-deploy arrangement documented by Hugo and GitHub. It retains the Hugo version used for the earlier chapter examples. Action versions are explicit too; they should be reviewed when maintaining the book. Hugo: hosting on GitHub Pages, Checkout action, Configure Pages action, Upload Pages artifact action, Deploy Pages action

Understand the parts you are relying on

An artifact here is a packaged build result passed between jobs. It is not another source commit. The github-pages environment records the deployment target and its URL. GitHub supplies the workflow's authentication; do not paste your own account credentials into this YAML file.

The ${{ ... }} expressions belong to GitHub Actions. They are not Hugo template expressions, even though both use braces. The shell script in the install step runs on GitHub's Linux runner, including when your own computer runs Windows.

Our starter uses plain CSS and no external theme, so this workflow does not install Node.js, Go modules, or a Sass toolchain. A future theme with extra build requirements would need corresponding changes. Copying a workflow does not automatically satisfy every theme's dependencies.

This is a small automated build-and-deploy pipeline. Chapter 14 will add the fuller CI/CD workflow: checks on proposed changes, clearer quality gates, and controlled deployment. For now, every push to main is a publishing action once this workflow is installed.

7.5 Publish and inspect the first deployment

Review the configuration and new workflow before recording them:

git status

git add hugo.toml .github/workflows/hugo.yaml

git diff --cached

git commit -m "Configure GitHub Pages publishing"

git push

Review the entire staged diff. In particular, confirm the real baseURL, the exact workflow file path, and the main trigger. There should be no unrelated edits in this commit.

Open the repository's Actions tab. Select Publish Hugo site and open the run associated with the commit you just pushed. The run should show a build job followed by a deployment job.

Wait for both jobs to finish successfully. If a job fails, open its first failed step and read the message before changing files. A successful push means the source reached GitHub; it does not mean Hugo built or Pages deployed successfully.

Open the website URL shown by the deployment or by Settings → Pages. Use that reported URL rather than guessing. The first deployment may take a little time to become available. GitHub: configuring a publishing source

Verify the actual website

Visit these on the published site:

• Home and every main navigation destination.
• The first article, including its screenshot and publishing checklist.
• The project detail page and its link back to the article.
• The footer's About link from a nested page.

Check that the stylesheet loaded and that the content is readable at a narrow width. Open a nested page directly in a new tab and reload it. Its address should remain on the published site's domain and project path, with no localhost address involved.

Finally, try the public URL in a private browser window while signed out of GitHub. For this public project site, visitors should not need your account or the Hugo server running on your computer.

7.6 Publish one small improvement

Open the first article's Markdown file. Add this item to the publishing checklist created in Chapter 6:

- Check the published page after deployment.

Save, preview locally, and check the diff. Then use the familiar cycle with one new final step:

git diff -- content/articles/first-learning-note/index.md

git add content/articles/first-learning-note/index.md

git diff --cached

git commit -m "Add a live-site check to the publishing checklist"

git push

Open the new Actions run, confirm that it corresponds to this commit, and wait for deployment to finish. Reload the published article and find the new checklist item. If it is not visible yet, check the deployment status before blaming the browser cache.

You have now completed the whole loop: edit, preview, review, commit, push, watch the deployment, and verify the live page. Repeat this loop for future small updates.

For this exercise, make edits in your local project. Editing independently in GitHub's browser interface would create remote commits that your local branch must first incorporate. We will introduce that collaboration workflow deliberately later.

7.7 Recognise a failed build without publishing a mistake

Start from a clean working tree after the successful update. We will create a temporary local configuration error.

In hugo.toml, remove the final closing quote from the baseURL line. Save and run:

hugo --minify --panicOnWarning

Hugo should fail while reading the TOML configuration. Read the error and locate the damaged line. Do not stage or push this experiment.

Review the isolated change and restore it:

git diff -- hugo.toml

git restore -- hugo.toml

hugo --minify --panicOnWarning

git status

The second build should succeed and status should be clean. As in Chapter 6, restoring the file is appropriate here because the only unstaged change in it was our deliberate mistake.

If a similar error reached GitHub, the failed build would prevent the dependent deploy job from publishing that run. Fix the source locally, check the build, commit the correction, and push again. A previously successful Pages deployment normally remains available when a later build fails.

A technically successful deployment can still contain inaccurate writing or a broken link. The workflow we have supplied does not verify facts, every destination, or accessibility. The live checks remain part of your publishing responsibility.

7.8 Your independent publishing task

Improve one sentence on the About page. Use the same cycle to preview, commit, push, and verify it at the public address. Choose a change you can recognise clearly on the live page.

Record the public URL somewhere useful, such as your project notes. Your latest committed and pushed version is the Chapter 7 checkpoint.

Completion check

• My local branch is connected to the intended GitHub repository.
• The repository contains source and history, while generated public/ output remains ignored.
• I can distinguish the repository URL, local preview, and public website URL.
• Pages uses GitHub Actions as its publishing source.
• Both build and deployment jobs completed successfully.
• I checked the live pages, nested links, stylesheet, and article image.
• My checklist update and independent About-page edit reached the live site.
• I repaired the temporary local configuration error before committing anything else.
• I understand that future pushes to main trigger publication.

Chapter 8 introduces the primary AI agent environment. With local preview, Git history, and publishing in place, you will be able to give an agent a small task and review its changes before they reach your website.

Troubleshooting when you need it

Custom domains, DNS, alternative hosts, detailed workflow security, and collaboration policies are beyond this first publishing exercise. Keep the working setup small and introduce those topics when the project needs them.

You can now write a page, recognise its HTML and CSS, save a Git checkpoint, and publish an update. Those skills make an AI agent more useful: you can give it a specific job and judge what it actually changes.

Our first job is small. The Resources page already contains useful links. You will ask an agent to add a short section explaining how a reader might use them. The result should be easy to inspect: one new heading and three bullets in one Markdown file.

We will use Codex CLI as the primary agent environment. The aim is to learn a repeatable working method, not to install every available AI tool. Alternative editor setups can use the same task and review criteria.

What you will be able to do

By the end, you should be able to:

• Start the agent in the intended Hugo project and inspect its working permissions.
• Provide a clear task, relevant files, boundaries, and observable success criteria.
• Review the changed files and rendered page independently of the agent's summary.
• Keep an accepted change in Git and recover from an isolated mistake.

Start from the working Chapter 7 project with a clean Git working tree (or switch to companion branch chapter-07 in ssg-playground). The chapter's local exercises also work if you have completed its source configuration but have not yet published. You need internet access and an account with access to Codex.

Check your account's current access and usage limits before starting. Signing in with ChatGPT uses the access available through that account or workspace; API-key sign-in uses separately billed API access. Installing a client does not provide unlimited model usage. We will use Sign in with ChatGPT and will not configure an API key in this exercise. OpenAI: authentication

8.1 Know what you are opening

An agent combines a model with tools that can inspect files, make edits, and run commands. Its usefulness depends on the tools, context, and permissions available in that session.

An ordinary chat without access to your files can suggest a change, but cannot establish that it changed your local project. An agent with file access can act on the project, so its output needs review as well as reading.

VS Code is an editor, not itself a particular model. An agent extension adds the relevant capabilities. Codex has an official IDE integration, including a VS Code extension; follow its own setup instructions if you later choose that interface. You do not need both interfaces for this chapter. OpenAI: Codex IDE extension

The CLI runs on your computer, but that does not mean its model runs offline. Relevant prompts and project context can be sent to the model service. Use the book's practice project and the account arrangements appropriate to your material.

8.2 Install, sign in, and check the project

Use the official Codex CLI installation page. Choose one installation route. The standalone installers below avoid introducing a separate Node.js setup solely for this chapter.

On Windows, in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

On macOS or Linux, in a terminal:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

These commands download and execute OpenAI's installer. Use the official page as the source for updated instructions. On a managed computer, follow your organisation's software-installation policy rather than changing system restrictions to force an installation.

Reopen the terminal if the installer requests it. Check:

codex --version

Keep the reported version in your notes; interface details can change. If Codex was already installed, check its version and continue without installing a second copy.

Sign in

Run:

codex login

Complete the browser sign-in using your intended ChatGPT account. GitHub authentication from Chapter 7 does not sign you into Codex. Do not paste passwords or account tokens into the Hugo project.

On Windows, complete the client's native sandbox setup when prompted. Some setup steps may require administrator approval. Use the current Windows sandbox instructions if your device cannot complete them. The native Windows route is sufficient for this plain Hugo project; WSL is a separate environment and is not an additional requirement for the book.

Confirm your starting point

In the terminal opened at the Hugo project root, run:

git rev-parse --show-toplevel

git status

hugo version

Confirm that Git reports your intended project, the working tree is clean, and Hugo is available in this terminal. Save or resolve your own unfinished edits before involving the agent. A clean starting point makes its changes distinguishable from yours.

If a usage limit or account restriction prevents agent access, you can still study the task and apply the comparison example manually. That practises the Hugo change, but it does not complete the hands-on agent exercise.

8.3 Give the project a short instruction file

Create AGENTS.md beside hugo.toml. If one already exists, read it and retain relevant guidance rather than replacing it blindly. For our starter, use:

# Project guidance



This is a small Hugo knowledge website using Markdown and plain CSS.



## Files



- Content lives in content/.

- The shared layout is layouts/all.html.

- The stylesheet is static/css/site.css.

- Site configuration is hugo.toml.

- The publishing workflow is .github/workflows/hugo.yaml.



## Working agreements



- Read the relevant source before proposing or making a change.

- Change only the source files requested for the current task.

- Preserve existing front matter, URLs, and authored facts unless the task asks otherwise.

- Do not invent experiences, qualifications, sources, or claims about the author.

- Use the installed Hugo; do not add dependencies or change the publishing workflow unless requested.

- Do not edit generated public/ or resources/ files by hand.

- When asked to check a change, run hugo --minify --panicOnWarning and report the result accurately.

- If a check cannot run, explain what prevented it and what remains unchecked.

- Leave staging, committing, pushing, and deployment to the reader unless explicitly delegated.

This file gives Codex reusable project guidance. It does not create operating-system permissions or guarantee compliance. Codex may also load applicable instructions from other locations; task-specific instructions still need to be explicit. OpenAI: AGENTS.md

Read the file yourself, then save a checkpoint:

git add AGENTS.md

git diff --cached -- AGENTS.md

git commit -m "Document the Hugo project's agent working agreements"

git status

The instruction file is ordinary project source and can be tracked. It is outside content/, so this starter will not turn it into a website page. Remember that pushing it to the public repository will make its text visible as source.

8.4 Ask the agent to inspect before it edits

Start a session from the project root:

codex --sandbox read-only --ask-for-approval on-request

Inside Codex, enter:

/status

Check the displayed project location and active settings. Slash commands go into the Codex interface; commands such as git status go into your ordinary terminal.

The read-only mode is useful for this first inspection. Requests to go beyond the configured boundary may trigger approval; do not approve file changes for this inspection task. The later workspace-write mode permits ordinary project edits and commands without asking about every one. Permissions can vary with installation and managed settings, so inspect the active session. OpenAI: approvals and sandboxing

Paste this request into the agent:

Read AGENTS.md, content/resources/index.md, layouts/all.html, and hugo.toml.

Do not edit files or run commands that modify the project.



Explain briefly:

1. Which file contains the Resources page's writing?

2. Which shared layout renders it?

3. What project-path prefix does the configured public URL use?

4. Which existing internal links could help a reader get started?



Point to the relevant files. If something is missing, say so instead of guessing.

Compare the response with the files. It should identify the Resources Markdown file, the shared all.html layout, and your configured project path. It should recognise the existing links to the first learning note and notebook project.

If the agent describes a different generator or invents files, correct the working directory or ask it to reread the named sources. Do not build the next task on a mistaken description.

Use /exit to return to your terminal. Run git status again; inspection should have left no source changes. OpenAI: CLI commands

8.5 Give it one bounded editing task

Restart from the same project root with permission to make local edits:

codex --sandbox workspace-write --ask-for-approval on-request

A new session should not be assumed to remember the previous conversation. We will provide the full task again. Check /status, then paste:

Read AGENTS.md and content/resources/index.md before editing.



Task: Help a first-time visitor use the Resources page.

Edit only content/resources/index.md.



Immediately after the introductory paragraph, add a section headed:

## How to use these resources



Add exactly three short bullets, using no more than 70 words in the new section.

- One bullet should explain when to consult the existing Hugo documentation link.

- One should link to the existing first learning note as a practical example.

- One should link to the existing notebook project page for the site's purpose.



Reuse the destinations already present in this file. Do not add external sources.

Preserve the front matter and all existing text and links below the new section.

Do not change layouts, CSS, configuration, dependencies, or workflow files.

Do not stage, commit, push, or deploy.



Run hugo --minify --panicOnWarning if the installed tools and permissions allow it.

If the check is blocked, report that rather than changing the environment.

Finish by listing changed source files, the check actually run and its result,

and anything I still need to inspect in the browser.

Watch the activity. The task authorises an edit to one source file and a local build. Generated output from that build is expected; hand-editing generated files is not. A request to install a framework, change your deployment workflow, or publish the result would not be necessary for this task.

A prompt sets the intended scope. The workspace sandbox is broader than this one-file instruction; it is not a per-file guarantee. Read any approval request in relation to the actual task rather than approving it automatically.

What makes this request useful?

You could make this edit yourself. That is a strength of the first exercise: the task is small enough for you to understand its entire result.

8.6 Review the files, not just the summary

When the agent finishes, read its report, then use /exit. In your normal terminal, run:

git status

git diff --name-only

git diff -- content/resources/index.md

git diff --cached

You should see one modified source file: content/resources/index.md. The staged diff should be empty because the agent was asked not to stage anything. Use status to notice unexpected new files too; an ordinary diff does not show untracked files.

Read every changed line. Check that:

• The new heading and three bullets appear in the requested place.
• The existing front matter, sections, and links remain intact.
• The new links reuse the correct destinations, including their relative-path form.
• The text describes the material accurately and does not invent claims about you.

Then run the build yourself:

hugo --minify --panicOnWarning

Check its exit result, not merely the presence of output in public/; old output can remain after a failed build. Next run hugo server, open its reported address, and visit Resources. Read the section and activate its links. Check the first learning note and project page, then return to Resources.

The agent's statement that a build passed is evidence about that command if it actually ran. It does not establish that the prose is accurate, every link works, or the page is easy to use. Ask for the command output when the report is unclear. An agent's second review can help, but it is not an independent guarantee.

One acceptable result for comparison

Your agent may choose different wording. This example shows the intended scale and destinations; it is not a transcript from a recorded agent run:

## How to use these resources



- Consult the [Hugo documentation](https://gohugo.io/documentation/) when you need details about configuration, content, or templates.

- Read [my first learning note](../articles/first-learning-note/) for a practical editing and checking example.

- Visit [my knowledge notebook project](../projects/learning-notebook/) to understand this website's purpose.

Preserve the existing introduction above this section and the two original sections below it. There is no need to replace the whole page with the example.

If the result needs correction

Give a precise follow-up such as:

Keep the new section, but restore the original text under Website publishing.

That existing text was outside the requested edit. Change only

content/resources/index.md, then show the corrected diff and rerun the build.

Do not stage, commit, push, or deploy.

If the session has been closed, start it again in the project and name the file and current issue explicitly. Do not assume an earlier conversation is automatically present.

If you want to discard the entire attempt, inspect status first. For this one previously tracked file, with no other valuable edits and no staged change, use:

git restore -- content/resources/index.md

If it was staged, use Chapter 6's unstage step first. Inspect unexpected changes separately; restoring this one path does not undo other files or remove newly created files. Avoid a broad cleanup command merely to make status look clean.

8.7 Keep the accepted result, then test your review habit

When the Resources edit meets the requirements, stop the preview and record it yourself:

git add content/resources/index.md

git diff --cached

git commit -m "Add guidance for using the notebook resources"

git status

If the staged diff includes any unrelated changes, resolve them before committing. The expected checkpoint contains only the accepted Resources edit; AGENTS.md was already committed separately.

A link can be wrong even when the build passes

Begin this short experiment from that clean checkpoint. In the new section only, change the first-learning-note destination from:

../articles/first-learning-note/

to:

/articles/first-learning-note/

Save and build again. Hugo can still build successfully. However, on the project site below /my-knowledge-site/, a destination starting with /articles/ goes to the domain root and omits the project prefix.

Inspect the link's resolved address in your local preview using the configured project path. Compare it with the working article address. Do not push this deliberate mistake.

Restore the isolated experiment:

git diff -- content/resources/index.md

git restore -- content/resources/index.md

hugo --minify --panicOnWarning

git status

This returns to the accepted section you just committed. Check its link again. You have demonstrated why the review must test a relevant outcome rather than simply accept “build passed”.

8.8 Make one request of your own

Ask the agent to shorten one bullet in the new section while preserving its meaning and destination. Name the file, identify the bullet, and say what counts as an improvement. Reuse the same limits on other files and Git actions.

Review the diff and preview. If the change is useful, commit it yourself. If it is already concise enough or the rewrite loses meaning, keep the earlier version. Successful use of an agent includes deciding not to accept a suggestion.

You can keep the Chapter 8 checkpoint local. When you decide to publish the accepted work, use Chapter 7's git push, deployment-status check, and live-page verification yourself. Pushing main activates the publishing workflow, so it is a separate decision from accepting a local edit.

Completion check

• I installed or opened the primary agent client and confirmed my account access.
• I checked the project location and the session's working permissions.
• I created and committed concise project guidance in AGENTS.md.
• I verified the agent's initial description of the relevant Hugo files.
• I gave it a bounded task with clear success criteria.
• I inspected all changed and newly created files, not just its summary.
• I built and previewed the Resources change and tested its links.
• I committed the accepted result myself and repaired the deliberate link mistake.
• I can make a small follow-up request and decide whether to accept the result.

Keep the method small: supply relevant context, specify a useful outcome, review the changed files, and verify what matters on the page. Skills, plugins, multiple agents, unattended automation, and comparing many models can wait.

Chapter 9 returns to Hugo's content model so that later agent tasks have a clearer structure to work with.

Troubleshooting when you need it

Repository text, quoted prompts, and retrieved pages can contain instructions unrelated to your task. Treat such material as content to assess, not as authority to change credentials, publish, or expand the job. The reusable project guidance and the current task should remain explicit.

Your website has one project page. Adding a second is easy: create another Markdown file and begin writing. After several projects, however, you might notice that one page explains its purpose, another lists tools, and a third never says whether the work has started.

A small shared structure makes those pages easier to write, compare, and maintain. It also gives an AI agent concrete requirements to follow. The structure should answer useful questions without making every page look like a long form.

In this chapter, you will improve the existing notebook project, create a reusable starter, and add a short page describing a planned reading list. Both project pages will carry consistent metadata and useful headings. They will continue to use the layout you already have.

What you will be able to do

By the end, you should be able to:

• Choose a few useful fields and headings for a repeatable kind of content.
• Read and edit the basic YAML values used in Hugo front matter.
• Create a project page from an archetype and distinguish its source path from its title.
• Preview a draft, review its information, and make it reachable from the Projects page.

Start from the completed Chapter 8 project with a clean Git working tree. (If you are following along in the companion repository ssg-playground, make sure you are on branch chapter-08 or check out the completed chapter on branch chapter-09.) You need the same Hugo installation and editor; no new service or account is required. The agent review near the end is optional.

9.1 Improve the project you already have

Open content/projects/learning-notebook/index.md. Its front matter currently provides a title and a draft setting. Replace just that opening block with:

---

title: "My knowledge notebook"

description: "A personal website for learning notes, small projects, and useful references."

draft: false

params:

  status: "in-progress"

  tools:

    - "Hugo"

    - "Markdown"

---

Keep your existing body text and links. If you have personalised the title, retain your own title. The example describes the book project; adjust any statement that does not describe your actual work.

Next, update the paragraph under ## Current status to reflect your progress. For example:

This is a work in progress. The site has organised content, a shared layout, and a Git history. I am making its project descriptions more consistent.

Before the final Back to Projects link, add:

## Next step



Use the same small set of fields and headings when describing another project.

Save, run hugo server, and open the notebook project through Projects. You should see the revised paragraph and new heading. Its title, navigation, and existing links should still work.

You will not see an automatic status label or tools list. The shared layout currently displays the page title and Markdown body. Storing another value in front matter does not automatically teach that layout to display it. The description is also not automatically added to the HTML head by our minimal starter.

That distinction matters: the source now contains information that later templates can use, while the visible improvement comes from the body text you just edited.

9.2 Decide what every project should explain

A content model is an agreement about the information a kind of content should contain. For this site, a project needs a name, a short description, a state of progress, and enough writing to explain the work.

We will use this small agreement:

The three status values are our editorial choices, not a built-in Hugo workflow. Hugo will not reject a fourth value merely because this table excludes it. We must review the values ourselves until we deliberately add validation later.

The table is also a scope limit. We do not need an owner field when every project belongs to the same author, a budget for a reading list, or a percentage complete that nobody can measure reliably.

Keep publication state separate from project progress

draft describes the page. status describes the project.

A page can be ready to publish even when its project is only planned. Conversely, a completed project can have an unfinished page that still needs editing. For example:

draft: false

params:

  status: "planned"

This combination is reasonable: readers can see an honest description of a plan. It does not claim that the planned work is finished.

Separate quick facts from explanation

The status value gives a short answer that a future layout can display or use for grouping. The Current status paragraph explains the evidence behind it. They serve different purposes, but must agree.

Avoid putting several sentences into status, or hiding the project's entire story in metadata. Keep the explanation in Markdown, where headings, links, and paragraphs are convenient to read and edit.

Likewise, an article and a project do not need identical models. A learning note might need a question and an explanation rather than a project status. We will improve one content family at a time.

9.3 Read only the YAML you need

Our pages already use YAML front matter between two --- lines. This section explains the few shapes introduced by the project model. We will keep using YAML for these pages and TOML for hugo.toml; the formats do not need to match. Hugo supports several front matter formats. Hugo: front matter

A named value

title: "My knowledge notebook"

title is the key; the quoted text is its value. Keep the colon and the space after it. The quotation marks are straight quotes, not typographic opening and closing quotes copied from a word processor.

Use quotes for the text fields in this chapter. They make the boundaries clear, especially when a title contains a colon:

title: "Reading list: website publishing"

If text contains a double quotation mark, you can put the whole value in single quotes instead, provided the text does not itself require handling an apostrophe:

title: 'Notes on "static" websites'

You do not need every YAML quoting rule to complete this project. Follow the simple examples and use your editor's error messages when a value becomes more complicated.

A true-or-false value

draft: false

false is a Boolean value. Keep true and false lowercase and unquoted. Writing "false" gives the YAML reader text instead of a Boolean; relying on later conversion makes the source less clear.

The distinction is useful beyond this one field. A name is text, a yes-or-no setting is a Boolean, and several tools form a list.

Related values under one key

params:

  status: "in-progress"

  tools:

    - "Hugo"

    - "Markdown"

Indentation describes the relationships. status and tools belong under params; the two list entries belong under tools. Use spaces, with two spaces for each level shown here. Do not use tabs for indentation.

params is a mapping: it groups named values. The dash-prefixed entries form a list. To add another relevant tool later, add another entry at the same indentation. To record that no tools have been chosen, use:

params:

  status: "planned"

  tools: []

An empty list is clearer than inserting a tool merely to fill a space. It also preserves the expected value shape for later template code.

Hugo provides recognised fields such as title, description, and draft. Put our custom project information under params, following Hugo's documented convention. Do not add a second params block if one already exists; add the new values within the existing block. Hugo: custom page parameters

A short source-reading check

Before continuing, point to the value that answers each question in your notebook project:

1. What should the page be called?
2. Is the page ready for an ordinary build?
3. Is the project finished?
4. Which tools does the page record?

If you can answer by reading the front matter, you know enough YAML for the exercise. More formats and larger data collections belong in Chapter 12.

9.4 Keep the page structure and address predictable

Chapter 3 introduced two filenames that look almost the same. They still have different jobs:

The folder containing an index.md is a leaf bundle. It groups one page with any resources that belong to it. A bundle can start with only its Markdown file; an image is not required. The section uses _index.md because it can contain project pages beneath it. Hugo: page bundles

Do not rename content/projects/_index.md to index.md to make the names look consistent. Their different names express a useful structural difference.

Under our current configuration, the new folder will give the second project an address ending in:

/projects/reading-list/

On the GitHub project site, that follows /my-knowledge-site/. The page title can be “My website reading list” while its folder remains reading-list. Changing the title alone will not change this folder-derived address in our starter.

Keep folder names short, lowercase, and separated with hyphens. Avoid changing an established folder name just because you improve a title; existing links may rely on its address. Hugo supports explicit URL overrides, but we do not need them for this exercise.

If a project later needs a screenshot, place it beside that project's index.md and use the relative image-link technique from Chapter 2. Keep site-wide assets such as the shared stylesheet in their existing location.

9.5 Make a reusable starter with an archetype

Copying an old project page can also copy its facts, links, and completion claims. A starter can provide the useful structure without carrying over another project's story.

Hugo calls a new-content starter an archetype. Create a folder named archetypes beside content, then create archetypes/projects.md. If that file already exists in your project, inspect it and adapt it instead of replacing unrelated work.

Use this complete starter:

---

title: "Replace with a project name"

description: "Replace with one sentence about the project's purpose."

draft: true

params:

  status: "planned"

  tools: []

---



## Purpose



Explain what this project is intended to achieve.



## Current status



Describe what has actually happened so far.



## What I have learned



Record a specific lesson, or explain that work has not begun.



## Next step



Name one concrete action.



[Back to Projects](../)

This starter is deliberately plain. It supplies text and headings without generating dates, guessing titles, or introducing template expressions. You will replace its prompts before publishing.

Archetypes can supply both front matter and body content. They are used when new content is created; editing an archetype does not rewrite pages you already created from it. That is why we updated the notebook project separately. Hugo: archetypes

Create the second project

Stop the preview with Ctrl+C. From the project root, run:

hugo new content --kind projects projects/reading-list/index.md

The command asks Hugo to use the projects archetype and create a file beneath content/. Do not add a second content/ prefix to the path shown. The --kind option selects the archetype for this creation step; it is not our project's progress status. Hugo: new content command