Pages
How a Markdown file becomes a URL, and what the writer does with it.
A page is one Markdown file under pages/. Its path is its URL.
| File | URL |
|---|---|
pages/index.md | / |
pages/faq.md | /faq |
pages/guides/install.md | /guides/install |
pages/api/index.md | /api |
Every page needs two things
Section titled “Every page needs two things”A title, in frontmatter. A page without one fails the
missing-title rule and cannot be committed.
A place in nav.yaml. A page that no section lists is an orphan, and the
commit is refused. See Navigation.
The three ways to edit a page
Section titled “The three ways to edit a page”The writer. A block editor at https://app.staleless.com. It edits the same file. Blocks
map to the directives on Blocks, so a page written in the
browser is a page a developer can read in a diff.
Your own editor. Edit the file in the repository and open a pull request. The writer shows the change once the branch is read.
An agent. docs_write over MCP stages a change. See
Agents and MCP.
Canonical form
Section titled “Canonical form”Staleless writes Markdown in one canonical form: consistent heading style, list
markers, emphasis and directive spacing. The not-canonical lint rule reports a
file that differs from it, and staleless lint --fix rewrites it.
Canonical form exists so a diff shows what a person changed and not how their editor formats. It never changes what a page says.
Links between pages
Section titled “Links between pages”Link with the published path, from the site root:
See [installing it](/guides/install).The linter checks every internal link and every heading anchor. A link to a page
that does not exist fails dead-link. A link to a heading that does not exist
fails dead-anchor.
Tip
When you move a page, add the old path to redirects.yaml in the same branch.
The redirect-conflict rule catches a move that left no redirect behind.
Drafts
Section titled “Drafts”Set draft: true in frontmatter. A draft page is built but never served. It is
absent from the site, the sitemap, search, Ask and the content API.
Deleting a page
Section titled “Deleting a page”Delete the file and remove it from nav.yaml in the same branch. A delete that
leaves the navigation pointing at nothing fails nav-missing-page.
Add a redirect unless the page was never published.