Pages, posts and docs

Everything you write is a markdown file in content/, and where it is decides what it becomes:

file	becomes	listed in
content/index.md	the home page, /
content/<name>.md	a page, /<name>/	the home page's links, if you add it
content/posts/<name>.md	a post, /posts/<name>/	the writings list, /writings/, and the feed
content/docs/<name>.md	a doc, /docs/<name>/	the docs' sidebar and /docs/

Every one but the 404 page is also listed in /sitemap.xml, for search engines.

Front matter#

Every file starts with a few lines between --- lines, its front matter:

---
title: First light
description: An optional line under the title, also for search engines.
date: 19-10-2026
---

line	for	what it is
title	everything but index.md	the title, at the top and in the browser's tab
description	anything	a line under the title, and the summary search engines and the feed show
date	posts, required; pages, docs	the day, as day, month and year: 19-10-2026. A page or doc with one says when it was updated
contents	posts, docs	true or false: whether this one has a contents list, whatever contents in config.toml says
layout	pages	page or compact; see below
order	docs	a whole number: where the doc comes in the docs, from 1
draft	anything	true to leave it out of the site for now; see below

A line that starts with # is a comment, for you alone. Any other line the build doesn't know stops it, as does a value it can't read, such as a date in another order: a typo such as descripton: would otherwise vanish without a word.

Drafts and dates#

A file with draft: true is left out of the site, and so is a post dated after today, until a build on or after its date. The build says how many it left out. To see them while you write, build with -drafts: go run . -serve :8000 -drafts.

A host that builds the site on every push publishes a post dated later at its first build after that day, so push something, or schedule a build, on the day.

Posts#

Posts are the writing a site is for: essays, notes, anything with a date. The writings list shows them newest first, grouped by year, and the feed at /feed.xml carries each one in full. A post keeps the capitals you write, has the licence from config.toml under it, and a link back to the writings above it. A site with no content/posts/ folder has no writings list and no feed, and nothing links to them.

Pages#

A page is anything outside the flow of posts: an about page, a contact page, a gallery. Link to it from the home page by adding it to links in config.toml. Its name can't be one the site already uses, such as posts, docs, writings or css: the build stops if it is.

Layouts#

A page comes in one of two layouts, chosen with layout in its front matter:

• page, the default: a link back to the home page, the title, then the text.
• compact: the home page's animation, the text centred, and the home page's links under it with Home in front, the page itself greyed out. It suits a page with a few lines, such as contact.

Docs#

Docs are a manual: pages meant to be read in order, like these. Each one's order sets its place; docs without one come last, by title. Every doc, and /docs/ itself, has the docs in a sidebar on the left on a screen wide enough, the one being read with its sections under it, and a search box at its top; on a narrow screen they fold up under the title, and open from Docs. Each heading in a doc carries a link to itself, shown when it's pointed at, for copying a section's address; and the docs either side are linked at the end. content/docs/index.md, if there is one, is the text of /docs/, above the list of docs; without it, /docs/ is the list alone. Docs can also be read from another repository's markdown, as it is: see docs from another repository. A site with neither has no docs section at all.