Markdown

Page content:

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:

md
---
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:

md
---
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:

md
```js
export function greet(name) {
  return `Hello, ${name}!`;
}
```
js
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:

md
```js [postdoc.config.js]
export default {
  base: '/docs/'
};
```
postdoc.config.jsjs
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:

md
```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:

md
::: code-group
```sh [npm]
npm install --save-dev postdoc
```

```sh [pnpm]
pnpm add --save-dev postdoc
```

```sh [yarn]
yarn add --dev postdoc
```
:::
npmsh
npm install --save-dev postdoc
pnpmsh
pnpm add --save-dev postdoc
yarnsh
yarn add --dev postdoc

The 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:

md
::: 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:

md
!!! 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:

md
| 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:

md
```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:

md
Euler's identity, $e^{i\pi} + 1 = 0$, links five constants.

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

Euler's identity, eiπ+1=0e^{i\pi} + 1 = 0, links five constants.

∫01x2 dx=13\int_0^1 x^2 \, dx = \frac{1}{3}

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:

postdoc.config.jsjs
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.

Edit this page on GitHub