Add a page #

View this page as Markdown

Prompt:

Add a page to the docs about the export command.

Also works: "Document the new setting." "Move the FAQ under Troubleshooting." "Hide the internal notes page from the site."

What your tool does #

• Reads the source folder's layout to choose the folder, the file name, and the next order.
• Writes the file with a front-matter block: title always, description in one sentence, and the other keys where the default is wrong.
• Links the new page from the pages that already mention the subject.
• On a rename or a move, keeps the old slug in redirects_from so that old links still reach the page.
• Runs tzdocs check --source docs and corrects what it reports, then runs the build and reports the success line.
• Asks nothing, because every step writes source files in your project. What happens without asking lists what the build writes.

What you need #

• Which section the new page belongs in, or that you want a new section created for it.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

• A corpus with a home page at its root, index.md, and the tool installed (Getting started).

Steps #

1. Choose the folder and the file name #

The file's path sets the page's slug, its URL path within the site: guides/first_guide.md becomes /guides/first-guide. The folder sets the section where it contains an index.md. A slug key overrides the derived slug, and the check reports one that puts the page in another folder. Follow the slug rules, which also list the reserved names and the paths that collide.

2. Write the front matter #

Start the file with a front-matter block between two --- lines. title is the only required key.

---
title: Export command
description: Export a corpus's pages to another format.
---

Add description in one sentence, and the other keys only where their default is wrong. Front matter lists the seven keys with their defaults and the value forms the parser accepts.

3. Set the order #

Give the page an order to place it among its siblings. On a folder's index.md, order places the whole section. A new section is a folder with an index.md that contains only front matter, its title and its order. A page without an order comes after the pages that have one. Order gives the full sort rules.

4. Hide the page, where it is not for readers #

Set visibility to any value other than public to hide the page. The build then leaves it out of the HTML, the navigation, the index, the manifest, the Markdown copies, and the whole text. --include-hidden builds it into all of them.

Visibility controls what the build writes and protects nothing. Where hidden pages are built, the site that serves the files controls who can read the HTML and the machine files. A hidden page's front matter is still parsed, so an error in it fails the default check or build.

5. Link the page #

Link to the page by its tree-relative path, such as /guides/export/, or by a path relative to the linking page, such as export.md. To link a heading, add its anchor as a fragment, such as #options, and read the anchor from the manifest. Links gives the link forms and the anchor rule.

6. Add an image or a file #

Put the image or the file in the source folder, beside the page or in a folder of its own, and refer to it by its path:

![The export flow](export_flow.png)

Download [the sample export](../files/sample.zip).

The build copies every file whose name does not end in .md to the same path in the output. It writes each reference as an address relative to the built page, so it works under any base path. A path that starts with / is read from the source folder. A file in a folder whose name begins with a dot is not copied. Images and other files gives the rules.

A reference to a file that is not there stops the build, and the check names the page and the path.

7. Rename or move a page #

Move the file, or change its slug, and add the old slug to redirects_from in the same change. The build writes a redirect stub at the old slug, so old links to the page keep working. Redirect stubs describes the stub. A link to a slug that no page or redirect has stops the build, and the check reports it.

8. Check and build #

Run tzdocs check --source docs, correct what it reports, and run the build. Check a corpus covers the loop.

Expected result #

The check prints its one success line and exits with code 0. The build then places the page in:

• the navigation, at its order;
• the index, under its section's heading;
• the manifest, with its headings and anchors;
• the whole text;
• a Markdown copy beside its HTML, at <slug>/index.md.

At a renamed page's old address, the build writes a stub that redirects to the new address.

Refusals #

A refusal stops the build before it writes anything, and the check reports it first. An advisory finding lets the build proceed. Refusals and findings gives every message's exact text.

Related #

• Page source lists the slug, front-matter, order, and link rules this guide applies.
• Highlight a code block gives the fence line for the code samples on the page.
• Check a corpus runs the check and corrects the findings.
• Output describes where the build writes the page in the tree and in the machine files.
• Glossary defines slug, route, section, and order.