Authoring guide

Every page in this wiki is a Markdown file. This guide covers where the files live, the frontmatter they take and the Markdown features that are available.

Everything here is public

Treat the content and public directories as public sources. Never publish secrets, credentials, private notes or anything you would not show a stranger.

Options that hide a page are not a privacy boundary:

• draft: true leaves a page out of production builds, but the file still sits next to public pages.
• pagefind: false leaves a page out of search, but it is still published.
• A page missing from the sidebar is still published at its URL.

Private material belongs outside this wiki’s source entirely.

Where files go

What	Location in the wiki app	Published as
Pages	src/content/docs/	one page per file
Static files	public/	copied as is
Sidebar	astro.config.mjs	navigation
Colours and type	src/styles/wiki.css	site styles

The file path sets the URL. src/content/docs/start-here/authoring.md becomes /start-here/authoring/. Files whose names start with _ are ignored.

Frontmatter

Each page starts with a YAML block. Only title is required.

---
title: Page title
description: One sentence for search results and link previews.
sidebar:
  label: Shorter sidebar label
  order: 2
---

Markdown

Standard Markdown works, including tables and fenced code blocks with syntax highlighting:

## A section heading

Text with **emphasis**, `inline code` and a [link to another page](/start-here/authoring/).

- A list item
- Another list item

Link to other pages with root-relative URLs such as /start-here/authoring/. Link to other sites with full https:// URLs.

Callouts use a directive:

:::note
Something worth pointing out.
:::

Note

This is how a note callout looks. :::tip, :::caution and :::danger are also available.

Adding a page to the sidebar

The sidebar is listed explicitly in astro.config.mjs. Add the new page’s slug (its path without the extension, for example start-here/authoring) to a group there. A page not listed in the sidebar is still published.

Previewing

pnpm wiki:dev starts a local preview at http://localhost:4322/. Search only works in a production build: run pnpm wiki:build, then pnpm --filter @pstr/wiki preview.