Build a Manual with Docusaurus #3: Writing Content — Code Blocks, Mermaid, Admonitions

Framework Docusaurus Documentation Static Site
3 min read

In #2 we set up the documentation’s skeleton with the sidebar and search. Now it’s time to fill it in. Technical docs need more than running prose. Commands should appear as code blocks, flows as diagrams, and things to watch out for in eye-catching callout boxes — so readers can move through quickly.

This series, Build a Manual with Docusaurus, runs in six parts.

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Documentation
  • #3 Writing Content — Code Blocks, Mermaid, Admonitions ← this post
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover three things: properly formatting code blocks, drawing diagrams with Mermaid, and highlighting with admonitions. Docusaurus has most of these features built in, so there’s little to configure.

Code Blocks — Titles and Line Highlighting #

Docusaurus provides code highlighting and a copy button by default. Add options after the language on the code fence to add a title and highlighting.

Title and highlighting on a code block 
```js title="src/app.js" {2}
function add(a, b) {
  return a + b; // This line is highlighted
}
```

title adds a filename band, and a number inside curly braces like {2} specifies the line to highlight. The copy button is added automatically to every code block.

Diagrams — Mermaid #

Mermaid is switched on with a separate theme. Install the package, then enable it in docusaurus.config.js.

docusaurus.config.js — enable Mermaid 
export default {
  markdown: { mermaid: true },
  themes: ['@docusaurus/theme-mermaid'],
};

Now opening a mermaid fence renders it as an actual diagram.

Mermaid flowchart 
```mermaid
flowchart LR
  A[Write post] --> B[Build] --> C[Deploy]
```

Admonitions — Highlighting Cautions and Warnings #

Content that says “you really must read this” shouldn’t get buried in running prose. Docusaurus has admonitions built in. Wrap with three colons and write the type after.

Writing an admonition 
:::warning Caution
Always back up first before applying to production.
:::

The types include note, tip, info, warning, and danger, each with its own color and icon, so information, caution, and danger are visually distinguished.

Splitting into Tabs #

Docusaurus’s strength is MDX, which lets you use React components inside Markdown. For content that branches, such as per-OS commands, show it with the Tabs component.

Splitting into tabs 
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="mac" label="macOS">brew install our-product</TabItem>
  <TabItem value="win" label="Windows">winget install our-product</TabItem>
</Tabs>

Wrapping Up #

In this post we covered code blocks with titles and line highlighting, Mermaid diagrams managed as code, and admonitions and tabs that highlight cautions and warnings. Most of it is built in, so there’s little to configure, and thanks to MDX the ceiling for expression is high. That’s Docusaurus’s strength.

In the next post we’ll send this documentation out into the world. We’ll walk through deploying to Cloudflare Pages and connecting a custom domain so anyone can reach it.

X