Markdown
Pages are Markdown files. Postdoc compiles them with marked, which supports GitHub Flavored Markdown, and adds the extensions on this page. HTML inside a Markdown file is kept as it is.
Front matter
A page can start with a YAML block between two --- lines:
---
title: Installation
description: How to install the CLI.
---Layouts read these values from page, so page.title is Installation here. The keys are up to you and your layouts. Postdoc itself reads a few of them: draft: true leaves the page out of builds, while the dev server still shows it, layout picks the page's layout by name, and title and description describe the page in llms.txt.
Variables
{{ name }} in a page is replaced with the front matter value name, and {{ appSettings.name }} with a value from the app settings:
---
product: Acme CLI
---
# Installing {{ product }}
{{ product }} is documented with {{ appSettings.name }}.Placeholders inside code are left alone, so code samples show them as written. A placeholder without a value stays in the page, so a typo is easy to spot.
Headings
Headings get ids, so you can link to them. The ids start with postdoc-: ## Install the CLI gets the id postdoc-install-the-cli, and a link to it is #postdoc-install-the-cli. The prefix is set in markdown.options.gfmHeadingId.prefix.
Code blocks
Fenced code blocks are highlighted with Shiki, which knows over 200 languages. Each block gets a copy button and a language label, and is rendered in a light and a dark theme:
```js
export function greet(name) {
return `Hello, ${name}!`;
}
```export function greet(name) {
return `Hello, ${name}!`;
}To show a file name above the code, put it in square brackets after the language, as code groups do for their tabs:
```js [postdoc.config.js]
export default {
base: '/docs/'
};
```export default {
base: '/docs/'
};The themes are github-light-high-contrast and github-dark-high-contrast, whose colours pass the page checks, unless you set others in markdown.syntaxHighlight.theme. To change them for one block, start the block with a comment, which is removed from the output:
```js
// light-theme=min-light dark-theme=nord
console.log('This block has its own themes.');
```Code groups
A code group shows several code blocks as tabs. Put the blocks between ::: code-group and :::, and give each tab a name in square brackets after the language:
::: code-group
```sh [npm]
npm install --save-dev postdoc
```
```sh [pnpm]
pnpm add --save-dev postdoc
```
```sh [yarn]
yarn add --dev postdoc
```
:::npm install --save-dev postdocpnpm add --save-dev postdocyarn add --dev postdocThe first tab is shown until the reader picks another. Switching tabs needs a script in the theme; the default theme includes one.
Callouts
Callouts, also known as admonitions, set a note, tip or warning apart from the text:
::: tip
Run `postdoc test` before you deploy.
:::
::: warning Renamed settings
`directories.content` is now `contentPath`.
:::Tip
Run postdoc test before you deploy.
Renamed settings
directories.content is now contentPath.
The types are info, note, tip, success, warning and danger. Text after the type replaces the default title. A callout can contain any Markdown, including lists and code blocks.
Postdoc also reads the MkDocs syntax, which helps when you move a site over:
!!! note "Optional title"
The content is indented by four spaces.The MkDocs types abstract, example, bug and quote are shown as info, info, danger and note.
Tables
Tables use the GitHub syntax, with two additions. A cell that ends with two pipes spans two columns, and a cell that contains only ^ merges with the cell above it:
| Command | Builds the site | Serves it |
| --- | --- | --- |
| `postdoc run` | Compiles pages on request and serves them ||
| `postdoc build` | Yes | No |
| `postdoc preview` | ^ | Yes || Command | Builds the site | Serves it |
|---|---|---|
postdoc run |
Compiles pages on request and serves them | |
postdoc build |
Yes | No |
postdoc preview |
Yes | |
Diagrams
A code block in the mermaid language becomes a Mermaid diagram:
```mermaid
sequenceDiagram
accTitle: Navigation without a reload
accDescr: The reader clicks a link, the Postdoc client fetches the next page from the server and swaps it in place.
participant Reader
participant Client as Postdoc client
participant Server
Reader->>Client: Clicks a link
Client->>Server: Fetches the next page
Server-->>Client: HTML
Client->>Reader: Swaps the page in place
```sequenceDiagram accTitle: Navigation without a reload accDescr: The reader clicks a link, the Postdoc client fetches the next page from the server and swaps it in place. participant Reader participant Client as Postdoc client participant Server Reader->>Client: Clicks a link Client->>Server: Fetches the next page Server-->>Client: HTML Client->>Reader: Swaps the page in place
Postdoc writes the diagram's source into a <pre class="mermaid"> element, and the theme draws it in the browser. The default theme loads Mermaid from a CDN, only on pages that have a diagram.
Screen readers can't read a diagram, so describe it with accTitle and accDescr, as in the example. Mermaid turns them into the diagram's accessible name and description.
Math
Math is rendered with KaTeX. Put inline math between single $ signs and block math between $$ lines:
Euler's identity, $e^{i\pi} + 1 = 0$, links five constants.
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$Euler's identity, , links five constants.
KaTeX writes each formula twice: as MathML, which screen readers read out, and as HTML that KaTeX's stylesheet lays out. Postdoc loads the stylesheet and KaTeX's fonts on the pages that have math, so your layouts don't need to. A formula that is wider than the page scrolls sideways.
Turn extensions off
Each extension has a switch under markdown.options, and all of them are on by default:
export default {
markdown: {
options: {
useCodeGroups: true,
useTables: true,
useAlertContainers: true,
useMermaid: true,
useMathExpressions: false
},
syntaxHighlight: false
}
};Setting syntaxHighlight to false turns highlighting off. To add your own syntax, pass marked extensions in markdown.extensions.