Today’s goal

After a few projects, one page explains its purpose, another lists tools, and a third never says whether the work has started.

• Agree what every project page should explain
• Build a reusable starter for new projects
• Add a second project: a planned reading list

A shared structure is easier to write, compare, maintain, and hand to an agent.

By the end of today you can

• Choose a few useful fields and headings for a kind of content
• Read and edit the basic YAML in Hugo front matter
• Create a page from an archetype, and tell its path from its title
• Preview a draft, review it, and link it from Projects

Start from Chapter 8 with a clean working tree (companion branch chapter-08).

Improve the existing project

Replace only the front matter of content/projects/learning-notebook/index.md:

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"

Then update its Current status paragraph and add a ## Next step section.

What you will not see

• No status label and no tools list on the page
• The layout shows only the title and the body
• Storing a value does not teach the layout to display it

The source now holds information later templates can use. The visible change came from the body text you edited.

Metadata is stored today and displayed in Chapter 10.

A content model: front matter

A content model is an agreement about what a kind of content contains.

A content model: the body

The three status values are our choice: Hugo will not reject a fourth. No owner, budget, or percentage: the model is also a scope limit.

Page readiness is not project progress

• draft describes the page
• status describes the project

draft: false
params:
  status: "planned"

An honest plan, published. status is the quick answer; the body gives the evidence. They must agree.

YAML: text values

title: "My knowledge notebook"
title: "Reading list: website publishing"
title: 'Notes on "static" websites'

• title is the key; after the colon and a space comes the value
• Quote text values: essential when the text contains a colon
• Straight quotes, never curly ones from a word processor
• Text containing "? Wrap it in single quotes

YAML: true, false, and lists

draft: false
params:
  tools:
    - "Hugo"
    - "Markdown"

• true and false are Booleans: lowercase, unquoted
• Indentation is structure: two spaces per level, never tabs
• params groups values; dashes make a list; [] is an empty one

Read the source

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?

Can you answer all four? You know enough YAML for today. More formats come in Chapter 12.

Custom values go under one params block; never add a second.

Predictable pages and addresses

• A folder with an index.md is a leaf bundle: the page and its own files
• The folder sets the address; renaming it breaks links. The title can change freely

An archetype: a starter for new pages

Copying an old project copies its claims too. Create archetypes/projects.md:

---
title: "Replace with a project name"
description: "Replace with one sentence about the project's purpose."
draft: true
params:
  status: "planned"
  tools: []
---

The archetype’s body

It continues with four headings, each with a prompt:

## Purpose

Explain what this project is intended to achieve.

## Current status

Describe what has actually happened so far.

Then What I have learned, Next step, and a Back to Projects link.

Create the second project

Stop the preview, then from the project root:

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

• --kind projects chooses the archetype; it is not the project’s status
• The path is inside content/: do not add content/ yourself
• It already exists? Inspect it; never force an overwrite

Editing an archetype later does not change pages already created from it.

Replace the prompts with the truth

title: "My website reading list"
draft: true
params:
  status: "planned"
  tools:
    - "Markdown"

Add a one-sentence description, and a body that says honestly: a proposal, nothing reviewed yet.

A page about a plan is not evidence that it was carried out.

Preview the draft

hugo server -D

Open the page directly, since Projects does not link to it yet:

http://localhost:1313/my-knowledge-site/projects/reading-list/

• Read the whole page; follow Resources and Back to Projects
• -D shows drafts; it does not make a page ready

Decide to publish

1. Change only draft: false, and keep status: "planned"
2. Restart with plain hugo server and reopen the page
3. In content/projects/_index.md, under ## Current work, add:

- [My website reading list](reading-list/): A planned collection of
  resources for learning website publishing.

The list is still manual: Chapter 10 automates it.

What draft does not do

• A draft is not private: its Markdown is readable in a public repository
• Turning a published page back into a draft does not reliably withdraw it: old output can remain
• A manual link can point to a page an ordinary build excludes

Keeping it as a draft? Keep draft: true, and add the Projects link later.

Break the front matter on purpose

Stop the server, and remove the closing quote from the title:

title: "My website reading list

hugo --minify --panicOnWarning

The build fails and names the file. The reported line may be where parsing gave up, not where the quote went missing. Restore the quote and build again.

Two different checks

Compare both pages with the model, and look for leftover starter prompts.

Try it yourself

• Rewrite the reading list’s Next step as a real action you could later confirm
• Review its tools list: keep Markdown, choose your real plan, or use []
• Do not add fields just to look sophisticated

Optional: ask the agent, read-only, to check both pages against the model. It can compare files with an agreement; it cannot confirm work done outside them.

Save the checkpoint

hugo --minify --panicOnWarning
git status
git add archetypes/projects.md content/projects/_index.md
git add content/projects/learning-notebook/index.md
git add content/projects/reading-list/index.md
git diff --cached
git commit -m "Define a consistent project model and add a reading-list project"

Open both new files before staging: git diff does not show untracked files.

When something goes wrong

Completion check

• Both projects use the agreed fields and headings
• I can tell page readiness from project progress
• I can read text, a Boolean, a mapping, and a list in YAML
• I created the second project from the archetype and replaced its prompts
• I checked it in the normal preview and tested its links
• I repaired the deliberate YAML mistake and reviewed the information
• I committed the four intended files