Skip to content

Authoring Primitives

A primitive is a canonical documentation concept in the mcp-zen-of-docs code surface. The server currently exposes 22 primitive identifiers through AuthoringPrimitive. Syntax differs by framework; the concept does not. The profile tool resolves any primitive to its framework-native form.

The 22 canonical primitives

Identifier What it represents
frontmatter YAML metadata block at the top of a page
heading-h1 Page-level H1 heading
admonition Callout block such as note, warning, or tip
code-fence Fenced code block with optional language and metadata
navigation-entry Sidebar, nav, or table-of-contents entry
snippet Reusable inline or block include/content snippet
table Markdown or HTML table
task-list Checkbox task list
image Embedded image with alt text and optional caption/title
link Inline link or cross-reference
footnote Footnote reference plus definition
tabs Tabbed panels for alternative content
diagram Mermaid, Graphviz, or similar diagram block
api-endpoint Structured endpoint/reference section
step-list Ordered procedural list for walkthroughs
badge Inline badge for version, status, or build state
card-grid Multi-card layout/grid
button Link styled as a call-to-action button
tooltip Hover-revealed explanatory text
math Inline or display math notation
formatting Inline emphasis beyond plain prose (highlight, superscript, etc.)
icons-emojis Inline iconography and emoji shortcodes

Code-truth note

The identifiers above match the source enum used by the MCP server. The examples below focus on the most common author-facing patterns rather than exhaustively showing all 22 primitives.

Common syntax reference

# H1  **bold**, _italic_, ~~strikethrough~~, [link](url)

frontmatter

---
title: Page Title
tags:
  - guides
---

---
title: Page Title
sidebar_position: 1
---

Starlight uses sidebar: { order: 1 } instead of sidebar_position.

admonition

!!! note "Title"
    Content indented 4 spaces.

:::note Title
Content here.
:::

::: info Title
Content here.
:::

import { Aside } from '@astrojs/starlight/components'
<Aside type="note" title="Title">Content here.</Aside>

button

[Primary](url){ .md-button .md-button--primary }
[Secondary](url){ .md-button }

No native button primitive in Docusaurus, VitePress, or Starlight — use a custom CSS class or component.

code-fence

my_module.py
return f"Hello, {name}"
VitePress uses [my_module.py] instead of title="my_module.py".

tabs

=== "Tab name"

    Content — blank line after header, 4-space indent on all content.

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
<Tabs>
  <TabItem value="a" label="Tab name">Content here.</TabItem>
</Tabs>

VitePress supports code-group for code-only tabs, not general content tabs.

table

| Column A | Column B |
|----------|:--------:|
| left     | center   |

diagram

flowchart LR
    A[Input] --> B[Process] --> C[Output]

Docusaurus/Starlight use the same Mermaid syntax after enabling a plugin. Docusaurus: @docusaurus/theme-mermaid. Starlight: starlight-mermaid.

footnote

A sentence with a footnote.[^1]
[^1]: The footnote text.

Not supported in Docusaurus or Starlight — use remark-footnotes or inline parenthetical notes.

formatting

==highlighted==   ^^underline^^   H^2^O   CO~2~

Only GFM ~~strikethrough~~ is available in Docusaurus, VitePress, and Starlight. Other extensions require custom CSS.

card-grid

<div class="grid cards" markdown>

-   :material-star: **Card title**

    ---

    Body. [:octicons-arrow-right-24: Link](page.md)

</div>

No native grid primitive in Docusaurus, VitePress, or Starlight — use a custom React/Vue component or CSS grid.

icons-emojis

:material-check-circle:   :octicons-star-24:   :smile:

import { Icon } from '@astrojs/starlight/components'
<Icon name="star" />  <Icon name="approve-check-circle" />

image

![Alt text](path/to/image.png "Optional title")

task-list and step-list

- Unordered item
- [ ] Task (unchecked)
- [x] Task (checked)
1. Ordered item

task-list maps directly to checkbox syntax. step-list is the same ordered-list concept used when the server generates procedural walkthroughs.

math

Inline: $E = mc^2$
Display: $$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

Zensical: native. Docusaurus/VitePress: add remark-math + rehype-katex. Starlight: add starlight-math.

tooltip

[Hover me](page.md "This text appears on hover")
*[HTML]: HyperText Markup Language
The HTML spec is long.

Not supported in Docusaurus, VitePress, or Starlight — abbreviation expansion and hover tooltips require custom components.

badge, snippet, navigation-entry, and api-endpoint

These four primitives are part of the canonical source vocabulary, but they are usually expressed through project-specific patterns rather than one universal Markdown shape:

  • badge — inline status badges in README/docs landing pages
  • snippet — reusable include or shared-content mechanism
  • navigation-entry — framework-specific sidebar/nav configuration
  • api-endpoint — structured endpoint sections in API docs

Use profile when you need the exact framework-native guidance for one of these primitives.

  • profile tool

    Resolve or translate any primitive to its framework-native syntax programmatically.

    Read more

  • Frameworks overview

    Full primitive support matrix and framework comparison.

    Compare frameworks