Build a Manual with Starlight #3: Writing Content — Code Blocks, Mermaid, asides

Framework Starlight Documentation Static Site
3 min read

In #2 we laid out the skeleton of the docs with the sidebar and search. Now it is time to fill it in. Technical docs need more than prose. Commands belong in code blocks, flows in diagrams, and things to watch out for in eye-catching boxes, so that readers can read quickly.

This series is Build a Manual with Starlight, in six parts.

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

In this post we cover three things: dressing up code blocks properly, drawing diagrams with Mermaid, and highlighting with asides.

Code Blocks — Titles and Line Highlights #

Starlight comes with a code block engine called Expressive Code by default. Thanks to it, titles, line highlights, and a copy button work with no extra setup. You write options after the language in the code fence.

Titles and highlights in code blocks 
```js title="src/app.js" {2}
function add(a, b) {
  return a + b; // This line is highlighted
}
```

title gives the file-name banner, and a number inside braces like {2} specifies the line to highlight. The copy button is attached automatically to every code block.

Diagrams — Mermaid #

Mermaid is not included in Starlight core. If you add a plugin like rehype-mermaid to astro.config.mjs, a mermaid fence renders as a diagram.

astro.config.mjs — add Mermaid 
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  markdown: { rehypePlugins: [rehypeMermaid] },
  integrations: [starlight({ title: 'Product Manual' })],
});

Now you write diagrams as code, the same way as with other tools.

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

asides — Highlighting Cautions and Warnings #

Content that says “you must read this” should not get buried in prose. Starlight calls highlight boxes asides and ships them built in. You wrap them in three colons and write the type.

Writing asides 
:::caution[Caution]
Always make a backup before applying this in production.
:::

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

Splitting into Tabs #

Content that branches, such as per-OS commands, is shown in tabs. You import the component Starlight provides in an MDX file and use it.

Splitting into tabs 
import { Tabs, TabItem } from '@astrojs/starlight/components';

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

Wrapping Up #

In this post we covered Expressive Code code blocks, Mermaid diagrams added via a plugin, and asides and tabs that highlight cautions and warnings. Starlight’s advantage is that code blocks and asides are powerful by default, so there is little to configure.

In the next post we send this doc out into the world. We will go over deploying to Cloudflare Pages and connecting a custom domain so that anyone can reach it by address.

X