Documentation Reference

Examples on this page will render with the proper styling within documentation.

To render only the documentation for previewing:

npm run docs

YAML Frontmatter

---
subtitle: Set an optional subtitle
search: false # Hide page from docs search
public: false # Hide page when FLAG_PUBLIC=true

# h1 sets the page title and browser tab
---

Single-Sourcing

Shared prose lives in _snippets/. Import a snippet to use it on a page:

import Example from "../_snippets/example.mdx"

<Example />

Leave YAML and # h1 on the host page. Snippet ## / ### headings are included in the host table of contents automatically, in the order the snippet appears on the page.

Conditional Content

public: false in YAML hides an entire page when FLAG_PUBLIC=true. Leave it off and the page will display in both builds.

To swap a chunk, not the page, use a fence — copy outside fences is always shown regardless of flags. The other fence is dropped at compile time, including its headings.

  • {.public} is kept when FLAG_PUBLIC=true
  • {.private} is kept when FLAG_PUBLIC=false
::: {.public}
Public-build copy (`FLAG_PUBLIC=true`).
:::

::: {.private}
Custom-install copy (`FLAG_PUBLIC=false`).
:::

For longer or generated copy, keep a sibling pair next to the host file and embed it. Shared _snippets imports are not rewritten. .ts, .sql, and .feature siblings render as a highlighted code block.

  • Unmarked name.mdx is the private file
  • name-public.mdx is the public file

A missing pair file fails the build.

::: {.embed src="conditional-embed"}
:::

src is relative to the file that contains the fence. Headings inside an embedded .mdx join the host table of contents.

Content

Headings

The sticky note table of contents are built from ## and ### headings.

Callouts

Text & Links

You can write bold and italic in the same sentence as the surrounding copy, and add links as usual.

Append {.button} to a markdown link for a bordered button. Append {.blank} to open a link in a new tab.

Drop {.heart} anywhere in prose for a peony-pink heart: . {.lock} and {.gear} work the same way: / .

Button

List Items

  • one
  • two
  • checked items
  • unchecked items
  1. first
  2. second

Code

Highlighting works for yaml, bash, typescript, and markdown.

export const title: string = "y2k guestbook";

# install dependencies
npm install
npm run dev

Layouts

Tabsets

::: {tabset} ::: splits on # h1 headings. Those headings become tab labels, not page titles.

Columns

::: {.columns} ::: have gaps between them by default, and no margin or padding on the sides:

A 25/75 mobile-responsive flexbox column example.

To add spacing on the top-level fence:

::: {.columns .pa2 .ma2}
::: {.columns .pl2 .mt2}

Tables

Pipe tables use a header row, a | --- | separator, and body rows:

DataWhoPurpose
Display name and message bodyAnyone who postsShow guestbook comments
Optional email (if the email field is enabled)Comment authorsVisible to site admins only
IP address (stored hashed)Comment submittersRate-limit abuse

Align a column with :--- (left), :---: (center), or ---: (right) in the separator row.