Blocks

Blocks

Content is CommonMark plus directive containers. Everything CommonMark supports works: headings, lists, tables, code fences, links, emphasis, images, quotes.

The blocks below are the additions. The writer offers each one from the slash menu, and writes exactly this syntax into the file.

Warning

An outer container takes more colons than the block inside it. ::::tabs holds :::tab. Get this wrong and the stray-directive rule reports it.

Hint

A callout. Five types: note, tip, warning, danger, info.

:::hint{type="warning"}
Deleting a project destroys its analytics. The pages stay in your repository.
:::

Expandable

Collapsed by default. Its content is still crawled and still searchable.

:::expandable{title="What if the certificate does not issue?"}
Check that the CNAME resolves, then re-read the hostname.
:::

Tabs

For a choice the reader makes once: an operating system, a language, a plan.

::::tabs
:::tab{title="macOS"}
brew install staleless
:::
:::tab{title="Linux"}
npm install -g staleless
:::
::::

Cards

A grid of destinations. href may be internal or external.

::::cards
:::card{title="Quickstart" href="/getting-started/quickstart"}
Connect a repository and publish.
:::
:::card{title="CLI" href="/developer-tools/cli"}
Run the checks in your build.
:::
::::

Note

A card is navigation, so the linter checks where it points. A card with a dead href fails dead-link.

Steps

A numbered procedure. Each step gets its own anchor.

::::steps
:::step{title="Install the app"}
Choose the repository and the branch.
:::
:::step{title="Write a page"}
Add it to nav.yaml in the same branch.
:::
::::

Code group

Two or more fenced code blocks as tabs. The site remembers the reader’s choice.

::::codegroup
```bash
curl -H "Authorization: Bearer $TOKEN" https://api.staleless.com/v1/pages
```
```javascript
await fetch('https://api.staleless.com/v1/pages', {
  headers: { Authorization: `Bearer ${token}` },
})
```
::::

Figure

An image with a caption. The caption is the body.

:::figure{src="/assets/publish-flow.png" alt="The publish flow"}
A change is staged, committed, then merged by a person.
:::

alt is not optional in practice: an image without it fails accessibility review, and the writer prompts for one.

Embed

A video or a design file, from an allowed provider.

:::embed{url="https://www.youtube.com/watch?v=..."}
:::

Arbitrary iframes are not accepted.

File

A download.

:::file{src="/assets/openapi.yaml" name="openapi.yaml"}
:::

Field

One parameter of an API reference. See API reference pages.

:::field{name="limit" type="integer" required="true"}
How many pages to return. Between 1 and 100.
:::

Two inline blocks

These are written inline rather than as containers.

Button. A call to action.

::button[Read the quickstart]{href="/getting-started/quickstart"}

Snippet. Includes a shared block by name. See Snippets.

::snippet{name="support-callout"}

Mermaid

A fenced block with the mermaid language renders as a diagram. It follows the site theme in light and dark.

```mermaid
flowchart LR
  draft --> commit --> merge --> published
```

What is not supported

Raw HTML is rejected by the unsafe-html rule. The block list above is the whole surface, and it is the same surface in the writer, in the repository and over MCP.