Docs as Code on Backend Engineering Strategy Tools

Document Tools — Pandoc, LaTeX, Typst, AsciiDoc, Sphinx

Thu, 04 Jun 2026 00:00:00 +0000

Tools adjacent to the Markdown/Hugo docs-as-code workflow — format conversion, typesetting, heavier markup languages, and documentation generators.

Pandoc

The universal document converter. Pandoc reads and writes dozens of formats: Markdown, HTML, DOCX, EPUB, LaTeX, RST, AsciiDoc, and more. The most common use in a docs-as-code workflow is converting Markdown to PDF (via LaTeX), to DOCX for stakeholders who need Word files, or to self-contained HTML for offline distribution. A single source in Markdown, multiple output formats on demand. Docker images make it easy to run without a local install — the full LaTeX stack is large but containable.

LaTeX

A typesetting system built for precision output — academic papers, technical documentation, books. LaTeX gives exact control over typography, equations, cross-references, and bibliography. The source is plain text markup that compiles to PDF. Steep learning curve, verbose syntax, but the output quality for complex documents (especially anything with mathematical notation) is unmatched. Pandoc uses LaTeX as the intermediate format when generating PDFs, so you often interact with LaTeX indirectly through a Pandoc pipeline rather than writing .tex directly.

Typst

A newer alternative to LaTeX with a friendlier syntax and faster compilation. Typst is designed from scratch for the same use case — precise typeset documents, scientific papers, equations — but the markup is more readable and the error messages are useful. Still maturing but gaining traction as a LaTeX replacement for teams starting fresh. Compiles to PDF directly; no intermediate format.

AsciiDoc

A markup language heavier than Markdown but lighter than LaTeX, designed specifically for technical documentation. AsciiDoc supports cross-references, admonitions (NOTE, WARNING, TIP blocks), includes (assembling a document from multiple source files), and detailed table and image control — things Markdown handles awkwardly or not at all. Asciidoctor is the primary processor (Ruby, with a Java port). Used heavily by Red Hat, the O’Reilly book toolchain, and projects that need a single-source publishing pipeline for both web and print output.

Sphinx

A documentation generator from the Python ecosystem, originally built for the Python language documentation. Sphinx reads reStructuredText (RST) or Markdown source and produces HTML sites, PDF (via LaTeX), and ePub. The key feature is its cross-referencing system — links between pages, auto-generated API docs from docstrings, and an index are all first-class. The Read the Docs hosting platform is built around Sphinx. Common outside Python too for any project that wants a structured documentation site with strong cross-referencing.

Resources

Site Navigation

Thu, 04 Jun 2026 00:00:00 +0000

Technical reference for the search, mindmap, and word cloud navigation on this site. The design approach is in Thinking: Site Navigation — Beyond the Menu.

Architecture overview

Three navigation modes, one data source:

Hugo build
 └── list.json.json template
 └── /public-notes/index.json ← built once
 ├── search.js (Fuse.js)
 ├── mindmap.js (D3.js)
 └── wordcloud.js (wordcloud2.js)

All three run entirely client-side. No server, no external search service. Hugo generates a JSON index at build time; JavaScript fetches it and does the rest.

The JSON index

Hugo outputs a JSON file for the public-notes section via a custom output format. The _index.md for the section declares both HTML and JSON outputs:

outputs:
 - HTML
 - JSON

The template at layouts/public-notes/list.json.json iterates all published pages recursively:

{{- $pages := where .RegularPagesRecursive "Draft" false -}}
[
{{- range $i, $page := $pages -}}
{{- if $i }},{{ end }}
{"title":{{ $page.Title | jsonify }},
 "url":{{ $page.RelPermalink | jsonify }},
 "section":{{ $page.Section | jsonify }},
 "subsection":{{ index (split $page.RelPermalink "/") 2 | jsonify }},
 "tags":{{ $page.Params.tags | default slice | jsonify }},
 "summary":{{ $page.Summary | plainify | truncate 160 | jsonify }}}
{{- end }}
]

Available at /public-notes/index.json after build. Each entry:

Field	Content
`title`	Page title
`url`	Relative URL
`section`	Top-level section (`public-notes`)
`subsection`	Second path segment (e.g. `infra-as-code`)
`tags`	Array from front matter, empty array if none
`summary`	Auto-generated from first ~160 chars of content

Search — Fuse.js

Fuse.js is a lightweight fuzzy-search library. It runs entirely in the browser against the JSON index — no server, no indexing step at build time beyond what Hugo already produces.

Initialisation:

fetch('/public-notes/index.json')
 .then(r => r.json())
 .then(data => {
 const fuse = new Fuse(data, {
 keys: [
 { name: 'title', weight: 3 },
 { name: 'tags', weight: 2 },
 { name: 'subsection', weight: 1.5 },
 { name: 'summary', weight: 1 }
 ],
 threshold: 0.35, // 0 = exact, 1 = match anything
 includeScore: true
 });
 });

Title matches rank highest, followed by tags, then section, then summary text. threshold: 0.35 allows minor typos and partial matches without returning garbage.

Trade-offs vs alternatives:

Fuse.js — zero build-time overhead, smallest setup, good enough for ~100 notes. Gets slower with very large corpora.
Pagefind — generates its own index at build time, better at full-text search, needs a build step integration. Worth switching to if the notes grow large enough that Fuse becomes slow.
Lunr.js — similar to Fuse, slightly more powerful query syntax, heavier.

Implemented as a Hugo shortcode (layouts/shortcodes/search-notes.html) — the CDN script, input, results container, and JS logic are all inline, same pattern as the carousel shortcode.

Mindmap — D3.js force simulation

D3.js force simulation lays out notes as nodes connected by edges. Nodes are coloured by subsection. Edges connect notes that share tags (strong) or belong to the same subsection (light).

Data model:

// nodes: one per page
const nodes = data.map(p => ({
 id: p.url, title: p.title,
 section: p.subsection, tags: p.tags
}));

// edges: shared tags (strength 0.8) or same subsection (strength 0.15)
const links = [];
for (let i = 0; i < nodes.length; i++) {
 for (let j = i+1; j < nodes.length; j++) {
 const sharedTags = nodes[i].tags.filter(t => nodes[j].tags.includes(t));
 if (sharedTags.length) {
 links.push({ source: nodes[i].id, target: nodes[j].id, strength: 0.8 });
 } else if (nodes[i].section === nodes[j].section) {
 links.push({ source: nodes[i].id, target: nodes[j].id, strength: 0.15 });
 }
 }
}

Forces:

d3.forceSimulation(nodes)
 .force('link', d3.forceLink(links).id(d => d.id)
 .strength(l => l.strength).distance(80))
 .force('charge', d3.forceManyBody().strength(-120))
 .force('center', d3.forceCenter(W/2, H/2))
 .force('collision', d3.forceCollide().radius(18))

Interaction: click a node to highlight its direct neighbours and hide unrelated edges. Click the background to reset. Drag nodes to rearrange. Scroll to zoom (zoom is applied to a <g> transform via d3.zoom).

Current limitation: most notes do not have tags in their front matter, so edges are mostly section-based. The graph becomes more useful as tags are added. Adding tags: to front matter of any note immediately creates cross-section connections in the mindmap.

Word cloud — wordcloud2.js

wordcloud2.js renders a canvas-based word cloud. Words are sections and tags from the index, sized by frequency.

Frequency counting:

const counts = {}, sectionOf = {};
data.forEach(page => {
 const sub = page.subsection || page.section;
 counts[sub] = (counts[sub] || 0) + 3; // sections weight more
 sectionOf[sub] = sub;
 page.tags.forEach(tag => {
 counts[tag] = (counts[tag] || 0) + 1;
 if (!sectionOf[tag]) sectionOf[tag] = sub;
 });
});

Sections are weighted 3× per page so they appear prominently even with sparse tags. Tags accumulate naturally as notes get tagged.

Click behaviour: clicking a word feeds it into the search input on the search page (if present on the same page) or navigates to /public-notes/search/.

Section colour map

Both mindmap and word cloud use the same colour map:

Section	Colour
infra-as-code	`#4CAF50` green
cloud-infrastructure	`#2196F3` blue
cicd	`#FF9800` amber
languages	`#9C27B0` purple
networking	`#00BCD4` cyan
security	`#F44336` red
observability	`#FF5722` deep orange
frameworks-tools	`#795548` brown
dev-environment	`#607D8B` blue-grey
docs-as-code	`#E91E63` pink
ai	`#673AB7` deep purple
hardware	`#8BC34A` light green

When a new section is added, add it to the colour map in both shortcodes (mindmap-notes.html and wordcloud-notes.html).

Adding tags to notes

Tags are the key input that makes cross-section connections appear in the mindmap. Add them to any note’s front matter:

---
title: "Terraform"
tags: ["iac", "terraform", "hcl", "state-management"]
---

Notes that share tags will be connected across section boundaries in the mindmap. The word cloud will show the tags sized by how many notes carry them.

No rebuild of the shortcode or template is needed — the JSON template picks up tags automatically at build time.

Diagrams as Code — Mermaid and PlantUML

Wed, 03 Jun 2026 00:00:00 +0000

Diagrams as code: describe a diagram in text, render it as an image. No drag-and-drop, no binary file that diffs as noise, no diagram that goes stale because it’s a PNG nobody updates. The source lives in Git alongside the code it describes.

Mermaid

Mermaid is a JavaScript-based diagramming tool with a simple, readable syntax. It renders natively in GitHub Markdown, GitLab, and many documentation tools — paste a fenced code block with mermaid as the language and the diagram appears inline. No server needed for basic use.

Flowchart:

```mermaid
flowchart LR
 A[Source] --> B{Build}
 B -- pass --> C[Test]
 B -- fail --> D[Notify]
 C --> E[Deploy]
```

Sequence diagram:

```mermaid
sequenceDiagram
 participant Client
 participant API
 participant DB
 Client->>API: POST /order
 API->>DB: INSERT order
 DB-->>API: ok
 API-->>Client: 201 Created
```

Other supported types: class diagrams, entity-relationship, state machines, Gantt charts, Git graphs.

The Mermaid live editor is the fastest way to iterate on a diagram.

PlantUML

PlantUML predates Mermaid and has a wider set of diagram types — UML sequence, class, component, deployment, activity, state, and non-UML types like C4 (architecture), BPMN, and Gantt. The syntax is more verbose than Mermaid but more expressive for complex diagrams.

PlantUML requires a rendering server (Java-based, self-hostable) or the hosted server at plantuml.com. Most IDE plugins (IntelliJ, VS Code) bundle a renderer.

Sequence diagram:

@startuml
actor Client
participant API
database DB

Client -> API : POST /order
API -> DB : INSERT order
DB --> API : ok
API --> Client : 201 Created
@enduml

Component diagram:

@startuml
package "Frontend" {
 [Web App]
}

package "Backend" {
 [API Server]
 [Worker]
}

database "PostgreSQL"

[Web App] --> [API Server]
[API Server] --> PostgreSQL
[Worker] --> PostgreSQL
@enduml

Which to use

	Mermaid	PlantUML
Renders in GitHub/GitLab	Yes, natively	No, requires plugin or pre-rendering
Setup	Zero	Rendering server or plugin
Syntax	Simple, readable	More verbose, more powerful
Diagram types	Core UML + Git/Gantt	Full UML + C4 + more
Best for	Quick diagrams in docs and READMEs	Complex architecture and UML diagrams

Resources

Hugo

Mon, 01 Jan 2024 00:00:00 +0000

Hugo is a static site generator written in Go. Content is Markdown, templates are Go HTML templates, and the output is plain HTML/CSS/JS — no server-side runtime, no database. Build times are fast even for large sites; most builds complete in under a second. This site is built with Hugo.

Structure

content/ # Markdown pages — mirrors the URL structure
layouts/ # Template overrides (Hugo prefers local files over theme files)
assets/ # CSS, JS, images processed by Hugo Pipes
static/ # Files copied as-is into the output
themes/ # Theme(s), typically pulled via Go modules
config.yaml # Site configuration

Content files use YAML front matter to set metadata:

---
title: "My Page"
date: 2026-06-04
draft: false
tags: ["example"]
---

Page content here.

Themes via Go modules

Themes are imported as Go modules in go.mod. To override a theme template or style, mirror the file path under layouts/ or assets/ — Hugo’s lookup order prefers local files over theme files, so the override takes effect without touching the theme itself.

Build and serve

# Serve locally with draft and future content enabled
hugo server -D --buildFuture

# Build to public/
hugo --minify

Sections and taxonomies

Hugo’s content model is built around sections (top-level directories in content/) and taxonomies (tags, categories). Each section and taxonomy gets its own listing page automatically. _index.md in a section directory controls the listing page’s content and front matter.

Resources

Markdown

Mon, 01 Jan 2024 00:00:00 +0000

Markdown is a lightweight markup language that converts to HTML. The syntax is designed to be readable as plain text — a # Heading looks like a heading even in a text editor, and **bold** reads naturally. John Gruber created the original spec in 2004; CommonMark later formalised an unambiguous specification. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, and syntax-highlighted fenced code blocks.

Core syntax

# Heading 1
## Heading 2

**bold** *italic* `inline code`

- unordered list item
- another item
 - nested item

1. ordered list
2. second item

[link text](https://example.com)
![alt text](image.png)

> blockquote

--- (horizontal rule)

Code blocks

Fenced code blocks with a language identifier get syntax highlighting in most renderers:

```go
func main() {
 fmt.Println("hello")
}
```

Tables (GFM)

| Column 1 | Column 2 |
|---|---|
| value | value |

Alignment is controlled by colons in the separator row: |:---| left, |---:| right, |:---:| centre.

Front matter

Static site generators (Hugo, Jekyll) extend Markdown with YAML front matter — a metadata block delimited by --- at the top of the file. Hugo uses it for titles, dates, tags, and draft status; it is not part of the Markdown spec but is the universal convention in docs-as-code workflows.

Resources

Reveal.js

Mon, 01 Jan 2024 00:00:00 +0000

Reveal.js is a browser-based presentation framework. Slides are HTML rendered in a browser — transitions, speaker notes, code highlighting, nested slides, and a presenter view all included. The source can be plain HTML or Markdown. Stored in Git, versioned, diffable, buildable in CI. No PowerPoint, no Keynote, no binary blobs.

The practical workflow for a docs-as-code setup: write slides in Markdown, serve with Hugo using the Reveal Hugo theme, export to PDF with DeckTape for distribution.

Hugo integration — Reveal Hugo

Reveal Hugo is a Hugo theme that turns a Hugo site into a Reveal.js presentation builder. Add the theme, create a content directory, and Hugo renders each section as a Reveal.js presentation.

Slides live in a Hugo content directory. Horizontal slides are separated by ---, vertical slides (a column within a section) by ___:

+++
title = "My Talk"
outputs = ["Reveal"]
+++

# First slide

---

# Second slide

Horizontal neighbour of the first.

___

## Second slide, vertical child

Press down to reach this one.

---

# Third slide

outputs = ["Reveal"] in the front matter tells Hugo to use the Reveal layout instead of the standard page layout.

Configuration

Reveal.js options set in config.yaml under [params.reveal_hugo]:

params:
 reveal_hugo:
 theme: "black"
 highlight_theme: "monokai"
 slide_number: true
 transition: "slide"

Per-slide overrides go in a front matter block on that slide.

Shortcodes

Reveal Hugo provides shortcodes for Reveal.js features:

{{< slide background-image="bg.jpg" >}}

# Slide with background image

{{< /slide >}}

{{% note %}}
Speaker notes — visible in presenter mode, not on screen.
{{% /note %}}

Exporting to PDF with DeckTape

DeckTape drives a headless browser through each slide and captures a PDF that preserves the rendered layout — fonts, colours, syntax highlighting. The simplest path is Docker:

# Export from a live URL
docker run --rm -t -v $(pwd):/slides \
 astefanutti/decktape \
 https://example.com/my-presentation slides.pdf

# Export from a local Hugo server (hugo server running on 1313)
docker run --rm -t --net=host -v $(pwd):/slides \
 astefanutti/decktape \
 http://localhost:1313/presentations/my-talk/ slides.pdf

DeckTape auto-detects the presentation framework. Override the output size with --size 1920x1080 if needed.