Write the documentation

This page says where a page of this site lives, how to add or change one, how to see the site on your machine and what the build checks. Start with the section that matches what you want to do.

Where a page lives

The text of the site is Markdown in docs/. The first # heading of a file is the title of its page. A topic is one page. A group of pages has an overview, docs/<group>.md, with one paragraph and a table that links its pages, and one file for each page in docs/<group>/<topic>.md.

website/docs-manifest.mjs lists every page, in the order of the sidebar. Each group has its own array there (startEntries, contributeEntries and so on), and contentEntries joins them. An entry has:

Key	Meaning
source	The path of the file from the repository root
slug	The route: contribute for an overview, contribute/documentation for a page of it
label	The name shown in the sidebar
group	The sidebar group, or a path of groups such as ['Build on Tilde', 'Contribute']
title	Optional. Replaces the title taken from the heading

The home page is website/src/content/docs/index.mdx, written by hand. CHANGELOG.md and THIRD-PARTY-NOTICES.md in the root are pages too, generated by tools: edit them with their tool, not on the site. The version in the header comes from <Version> in Directory.Build.props.

Never edit website/src/content/docs/generated/ or website/public/generated/. The import replaces them at every build, and Git ignores them.

Add a page

1. Write the file in docs/, starting with a # title.
2. Add an entry to the array of its group in website/docs-manifest.mjs, after the page it follows.
3. Add a row to the table of the overview of the group.
4. Run the tests and the build (see below).

The tests fail when a file of docs/ is not in the manifest, when two entries share a slug or a source, and when an array holds pages of more than one group.

The rules of a page

• A page has one topic and at most 150 lines of source, blank lines included. A page that does not fit is split in two, never excused.

• The first line says what the page is for. Then comes what to do first, then the details.

• The text is plain English, in short sentences, in the present tense, in the first person or neutral. There are no exclamation marks and no marketing words.

• Every command is on its own line in a fenced block. Keys are written j, Ctrl-d, Enter. Configuration keys and paths are in backticks.

• A page says only what the code does. A feature that is not in the code yet gets this aside, as the first line under the title:

  :::note[Planned]
  This page describes <feature> as it will be in the release after v<X>. The current release does not have it yet.
  :::

• A page that is not written yet holds its title and the sentence This page is not written yet. and nothing else. A written page never keeps that sentence. A page like that fails the build, because stubsAllowed is false in website/scripts/check-pages.mjs: an unwritten page is never published.

Links

Write links in Markdown, as relative paths to the source file, as you would in the repository. Never use raw HTML for a link or an image: the import rewrites only Markdown.

• A link to a page of the manifest becomes the route of that page and keeps its #fragment.
• A link to an image copies the image into the site.
• A link to any other file or folder of the repository becomes a link to it on Codeberg, at the revision of the build.
• A link with a scheme (https:) and a link inside the page are left alone, and code blocks are never touched.

The import stops and names the file and the line when a link points nowhere or outside the repository, and when a page has no title. It also stops when a slug is invalid or used twice. The previous output stays in place.

See it on your machine

The site needs the Node version of website/.nvmrc. With nvm:

cd website
nvm use
npm ci

npm run dev

The site is at http://localhost:4321/Tilde/. The import runs once, when the server starts: after you edit a page in docs/, restart the server. Stop it with Ctrl-c.

What the build checks

Run this from the root of the repository before a pull request. It is what the site workflow runs.

scripts/build-site.sh

It runs these steps in order, and the first one that fails stops the build:

1. npm ci and npm test: the tests of the importer, the manifest, the link check, the page check, the version and the theme.
2. The import of docs/ into the site, with the revision for the source links taken from TILDE_DOCS_REF (develop when it is empty).
3. The page check (website/scripts/check-pages.mjs): the limit of 150 lines.
4. The Astro build, with the search index.
5. The link check (website/scripts/check-links.mjs), on the built HTML: every local link, image and #fragment exists, every page of the manifest exists, no anchor appears twice on a page, and the search index was built. Addresses outside the site are not fetched.

npm run preview in website/ serves the built site. To publish it, see Releases and CI.