Content

How a markdown file becomes a page.

Title and description

The title is the title in the frontmatter, else the first # heading, else the file name. The description is the description in the frontmatter, else the first paragraph of prose. Badges, tables, quotes, HTML and code blocks are skipped, and a # comment inside a code block is never read as a title.

Order

Pages sort by file name. Put order: 1 in the frontmatter to move a page up. The value must be a number: check reports order: "1" as an error.

Tags

Put tags in the frontmatter, a list or one comma separated string, and the index page of the collection gets a filter bar with a button per tag. Tags are trimmed, and UI and ui are the same tag. See CatalogFilter.

Side card

A page with meta (a list of label and value) and links (a list of label and href) in its frontmatter shows a card of details beside its text. An unknown key in them is a card finding. A link of the card that leads to a file that is missing or excluded is a links or excludedLinks finding, like the same link in the text. See A detail page with a side card.

Links

Write ordinary relative links, the ones that also work on GitHub.

Links inside code are never touched.

Callouts

Start a blockquote with > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] or > [!CAUTION] on a line of its own, the alert syntax that GitHub also renders, and it becomes a callout with its own icon, color and visible label. The marker line is removed, and the rest can hold paragraphs, lists and code. A blockquote without a marker, or with a name that is not one of these five, stays a plain blockquote, and a marker inside code is never touched. See Callouts for each kind.

What check finds in the content

sitekit check reads the markdown as data, and the build prints the same findings when it ends. Each finding is one line, file:line: severity: message, for example docs/guide.md:42: warning: Link "./nope.md" does not match any file. The line is the one that holds the link, the image, the heading or the frontmatter key, and for a side card the key inside its meta or links item. check prints the count and exits with 1 when any finding has the severity error. The build prints the findings and never fails on them, so check is the one that decides.

The kinds are the keys under check. What each one finds, and its default severity, are in the configuration reference, and Options: content checks and publishing shows a line that each kind prints.

Set the severity of a kind in sitekit.config.json with error, warning or off. A kind you do not set keeps its default:

"check": {
  "links": "error",
  "frontmatter": "off"
}

A name under check that is not a kind fails the build and the check, and the message names it and lists the kinds.

What the check reads, and what it does not:

• It reads inline links and images, [text](./file.md) and ![alt](./image.png), and an image inside a link, as in a badge. Links written as references ([text][ref]) are not read.
• Code is never read. A link, a heading or a marker inside a fenced block or a code span is not reported, the same rule the link rewriter follows.
• A web address, a mailto: link and a path that starts with / are not checked, for links and for images.
• A heading anchor is its text in lowercase, without punctuation, with a hyphen for each space, and a repeated heading gets -1, -2, the way the page renders it. The title that the page shows at the top is not a heading you can link to. An id or name written in HTML counts as an anchor.
• An anchor is checked only against pages that are on the site. A link into an excluded page, or into a file that is only in the repository, is not checked for its anchor.
• The changelog is not checked for repeated headings, because Added and Fixed come back under every version.

Code blocks

A fenced block can have a title, highlighted lines and added or removed lines, written after the language, such as ts title="src/config.ts" {2,4-6}. Every block has a button that copies its code. See Code blocks for the syntax, what the button copies and what it does without JavaScript.

Variables and snippets

A version number, a package name or a command that appears in many pages can be written once.

Variables. Write {{ version }} in prose, in a heading, in link text or in the frontmatter, and the build replaces it. version is read from the package.json of the repository (or site.version in the config). Other names are declared under vars in sitekit.config.json, with string values:

{ "vars": { "package": "@acme/widget" } }

A variable is replaced before the page is read, so the title, the description, the search index, llms.txt and the Markdown copy all show the final text. In a code span or a fenced code block it is left as written, which is how this page can show the syntax. A name that is not declared stays as written and is a variables finding: a warning with the file and line, from sitekit check and from the build. Both kinds follow check in the config, so "check": { "snippets": "warning" } lowers a missing snippet to a warning. A vars entry wins over the version of the package.

Snippets. A file in the snippets/ folder at the root of the repository is included with a comment alone on its line:

<!-- include: requirements.md -->

The indentation of the comment goes in front of every line of the snippet, so an include inside a list item stays in the item. A snippet can use variables, but it cannot include another snippet (one level only). A snippet that does not exist, or an include inside a snippet, is a snippets finding: an error, so sitekit check fails, and the build prints it with the file and the line. The snippets/ folder is not published as pages. An include inside a code block is shown as written.

On GitHub. The comment is not shown, so a page reads correctly without the snippet in it (the text just is not there). {{ version }} is shown as literal text, because GitHub does not replace it. Use a variable where that reads well as a placeholder, and a snippet where the page must read complete on the site only. A page that uses neither is built exactly as before.

Exclude and replace

anonymize.excludePaths keeps files from being read at all. anonymize.replace swaps literal text everywhere, for a client name or an internal host. The other keys of the group are in the configuration reference.