Writing content

Writedocs content is standard Markdown, with MDX components layered on top where you need them. This page is itself a working example of most of what’s covered below — view its source at example/docs/guides/writing-content.mdx in the repo to see the raw Markdown behind each section.

Headings

Use ## for major sections and ### for subsections within them — that’s exactly how this page and every other page in this fixture are structured. Avoid a top-level #; the page title from frontmatter already renders as the <h1>.

## A major section
### A subsection within it
#### Rarely needed, but supported

Headings get anchor IDs automatically, so ## Headings above is linkable as #headings.

Text formatting

Standard Markdown emphasis works as expected: bold text, italic text, bold and italic, and inline code. You can also strike through text, and mix links to other pages or external links directly into a sentence.

Lists

Unordered lists:

• First item
• Second item
  • A nested item, indented two spaces
  • Another nested item
• Third item

Ordered lists:

1. Install Writedocs
2. Create writedocs.json and docs/
3. Run writedocs dev
4. Run writedocs build when ready to ship

Blockquotes

Blockquotes render as an indented, tinted block with a colored left border — useful for pulling out a single important sentence without reaching for a full Callout.

Tables

Standard GitHub-flavored Markdown tables work without any extra syntax:

Code blocks

Fenced code blocks are syntax-highlighted automatically based on the language tag:

interface DocsConfig {
  name: string;
  navigation: NavItem[];
}

npx writedocs build ./my-docs

For showing the same command across multiple package managers, wrap fenced blocks in a Tabs component instead of listing them one after another — see the Components guide.

Diagrams (Mermaid)

A ```mermaid fenced block renders as an actual diagram, not highlighted code — Mermaid’s own syntax, parsed and drawn client-side:

Flowcharts, sequence diagrams, state diagrams, and everything else Mermaid supports all work the same way — just fence it as mermaid instead of a language name. The diagram follows the site’s light/dark toggle automatically.

Math (LaTeX)

Wrap LaTeX in a single pair of dollar signs for inline math, or a double pair on their own lines for a standalone block equation — both render as real typeset math (via KaTeX) at build time, not an image or a client-side widget:

The Pythagorean theorem states that $a^2 + b^2 = c^2$ in a right triangle.

$$
E = mc^2
$$

The Pythagorean theorem states that $a^2 + b^2 = c^2$ in a right triangle.

A lone dollar sign with nothing to pair it with — a plain price mention, say — is left as ordinary text. But two or more dollar signs anywhere in the same paragraph can pair up and try to render as math even when none of them were meant to, including one written inside inline code — so keep a stray dollar sign’s own paragraph free of any other dollar sign, or back-slash escape it:

This plan costs \$50, that one costs \$80.

This plan costs $50, that one costs $80.

Horizontal rules

Use three dashes on their own line to add a visual break between unrelated sections:

Content resumes here, below the rule.

Snippets

Reusable content — MDX prose, or a real React component — lives in a snippets/ folder next to docs/ and is pulled into a page with a plain import:

import QuickTip from '../../snippets/quick-tip.mdx';

<QuickTip subject="snippets" />

Snippets can also be .jsx/.tsx files — genuine React components, hooks included, hydrated in the browser with a client:* directive where needed. See docs.json-examples/00-kitchen-sink/ in the Writedocs repo for a complete example covering both MDX and React snippets.

Combining Markdown and components

Regular Markdown and MDX components can be freely interleaved. For example, a callout can sit directly between two paragraphs of plain prose without any special handling:

Here’s a paragraph explaining some context before an important note.

And a paragraph continuing the explanation afterward, exactly as if the callout weren’t there.