Build a Manual with Hugo #3: Writing Content — Code Blocks, Mermaid, Callouts

Framework Hugo Documentation Static Site
4 min read

In #2 we shaped the doc’s skeleton with the sidebar and search. Now it’s time to fill it in. Technical docs need more than running prose. Commands belong in code blocks, flows in diagrams, and cautions in boxes that stand out — that’s what lets readers read fast.

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

  • #1: From Install to Your First Doc
  • #2: Sidebar and Search — Shaping the Information Architecture
  • #3: Writing Content — Code Blocks, Mermaid, Callouts ← this post
  • #4: Deploying to Cloudflare Pages and Connecting a Domain
  • #5: Multilingual Content and Versioning
  • #6: Maintenance — Search Index, Accessibility, Documentation Culture

This post covers three things: styling code blocks properly, drawing diagrams with Mermaid, and emphasizing with callouts. All of these are features Hextra layers on top of standard Markdown.

Code Blocks — Filename and Line Highlighting #

The most basic is a code block wrapped in a fence. To this, Hextra adds a few things. Write options in curly braces after the language on the code fence.

Adding a filename to a code block 
```js {filename="main.js"}
console.log("hello");
```

Written this way, a main.js filename band attaches above the code block. Since it’s clear at a glance which file the code belongs to, it’s especially useful in explanations that move between several files.

You can also highlight specific lines or add line numbers.

Line highlighting and line numbers 
```py {filename="app.py",hl_lines=[2],linenos=table}
def add(a, b):
    return a + b  # this line is highlighted
```

Use hl_lines to specify the lines to highlight and linenos=table for line numbers. The copy button is added automatically by Hextra to every code block, so there’s nothing else to touch.

Diagrams — Mermaid #

When you explain an architecture or a flow by drawing an image directly, you have to recreate the image file every time you need to update it. Mermaid writes diagrams as code. Because it’s text, it’s version-controlled with Git and easy to edit. Just open a fence with the mermaid language.

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

Hextra renders this block into an actual diagram at build time. Beyond flowcharts, you can use any format Mermaid supports as-is — sequence diagrams, class diagrams, Gantt charts, and more.

Callouts — Emphasizing Cautions and Warnings #

Content that says “you must read this” can’t be buried in running prose. Hextra provides emphasis boxes via the callout shortcode.

Using a callout 
{{< callout type="warning" >}}
Always back up first before applying this to production.
{{< /callout >}}

type can be info, warning, or error; omit it for a default gray box. Each type has a different color and icon, so you can visually distinguish information, caution, and danger.

By the way, to show a shortcode as-is inside a code block as in the example above, you have to use Hugo’s escape notation {{< >}}. Write it plainly and Hugo will execute the shortcode, rendering a real callout rather than a code example. It’s a trap you step on often while writing docs, so we’ll revisit it in #6.

Other Blocks — Tabs and Steps #

When you want to collapse a long explanation or split it up by operating system, tabs are handy.

Splitting with tabs 
{{< tabs items="macOS,Windows" >}}
  {{< tab >}}brew install ...{{< /tab >}}
  {{< tab >}}winget install ...{{< /tab >}}
{{< /tabs >}}

For order-sensitive procedures like installation, you can number them with steps. These shortcodes are built into Hextra, so you can use them right away with no extra installation.

Wrapping Up #

In this post we covered code blocks that carry filename and line highlighting, Mermaid diagrams managed as code, and callouts that emphasize cautions and warnings. Get this far and you have docs that look good locally.

In the next post we send these docs out into the world. We’ll cover deploying to Cloudflare Pages and connecting a custom domain so anyone can reach them by address.

X