How to Write Technical Documentation with Mermaid Diagrams and Table of Contents in a Lightweight Browser Markdown Editor

You're Documenting Like It's 2010 (And Your Readers Can Tell)

Most developers still treat technical documentation like an afterthought — something to throw together in a Word doc or a bloated wiki system right before shipping. You copy-paste screenshots of architecture diagrams, manually number your sections, and pray the formatting holds when someone else opens the file. Three weeks later, nobody can find anything, the diagrams are outdated, and your "documentation" is a graveyard of broken image links.

Here's the shift: a lightweight browser markdown editor eliminates almost all of that friction. You write in plain text, render diagrams with Mermaid syntax, auto-generate a table of contents, and publish — all from one browser tab. No installs. No file sync headaches. No design decisions.

This guide walks through the exact workflow, step by step, for a specific reader: the solo developer or small team lead who needs to ship clean technical docs for an API, internal tool, or side project without spinning up a full documentation site.

The Wrong Way: Over-Tooling Your Docs

Mistake #1 — Reaching for Heavy Documentation Platforms Too Early

A common trap: you start documenting and immediately think "I need a documentation site generator." You install a static site generator, pick a theme, configure plugins, fight with version mismatches for two hours, and then write exactly 200 words of actual documentation. The tool became the project.

A browser-based markdown editor strips that away. You open a tab, type, and your content renders live. The barrier between "thinking" and "writing" drops to zero.

Mistake #2 — Pasting Screenshots of Diagrams

Architecture diagrams as PNGs are a maintenance nightmare. You change one component name, and now you're back in a drawing tool, re-exporting, re-uploading, and re-linking. Multiply that by every doc update and you've created a system nobody wants to touch.

Mermaid diagrams solve this. They're text-based. You edit a line of code, and the diagram updates instantly. No drawing tools. No image files. No broken references.

Mistake #3 — Manually Numbering Sections

You write "1. Introduction," "2. Getting Started," "2.1 Installation" — by hand. Then you insert a new section between 1 and 2, and every number below it breaks. A table of contents generated from your headings handles this automatically.

Let's fix all three.

Step 1 — Pick a Browser Markdown Editor That Supports Live Preview and Mermaid

Not every markdown editor renders Mermaid out of the box. Some treat it as raw code blocks and show nothing. Before committing to one, check two things:

Live split-pane preview: You see your rendered markdown on one side while you type on the other. This matters because technical docs are visual — you need to see your diagrams and formatting the moment you write them, not after a build step.

Native Mermaid rendering: The editor should render mermaid code blocks into actual diagrams in the preview pane, not just syntax-highlight them. If you have to install a plugin or run a separate build to see your flowchart, the editor is too heavy for this workflow.

A lightweight browser markdown editor wins here because there's nothing to install. You bookmark it, open it, and start writing. Your docs live as .md files you can save locally, push to a repo, or paste into any platform later.

Step 2 — Structure Your Document With Heading Hierarchy

Think of your headings like the frame of a house. The structure determines everything that follows — including your table of contents.

Use this simple hierarchy:

- H1 (one per document): The document title. Example: "Payment API Reference" - H2: Major sections. Example: "Authentication", "Endpoints", "Error Codes" - H3: Subsections within an H2. Example: under "Endpoints" → "Create Charge", "List Charges", "Refund Charge"

Keep it to three levels max for most technical docs. Going deeper than H4 makes your table of contents unreadable and signals that your document is trying to do too much — split it into separate files instead.

Here's a concrete example. Say you're documenting a payment API with 12 endpoints. A flat structure gives you 12 H2s in a row — overwhelming. Group them:

``` # Payment API Reference

## Authentication ## Endpoints ### Create Charge ### List Charges ### Refund Charge ### Retrieve Customer ### List Customers ## Webhooks ## Error Codes ## Rate Limits ```

Nine top-level entries instead of twelve flat ones. Your table of contents becomes scannable. Readers find "Refund Charge" under "Endpoints" in seconds, not after scanning a wall of links.

Step 3 — Generate a Table of Contents Automatically

In a good markdown editor, the table of contents builds itself from your heading structure. You don't type it. You don't number it. You don't maintain it.

Here's how it works in practice:

If your editor supports TOC generation: Look for a button or shortcut that inserts a TOC block. It scans your headings and produces anchor links. Add a new H3? The TOC updates on the next render. Delete a section? It disappears from the TOC. Zero manual work.

If you need a manual TOC marker: Some editors use a placeholder like [TOC] or <!-- toc --> at the top of the file. When the editor renders, it replaces that marker with a linked list of your headings.

The rule: never hand-type a table of contents for technical documentation. If you're manually maintaining section numbers or anchor links, you're doing work the editor should do for you. Every manual edit is a chance to introduce a broken link — and broken TOC links are one of the fastest ways to make readers lose trust in your docs.

Step 4 — Add Mermaid Diagrams Where They Actually Help

Not every section needs a diagram. Use Mermaid where visual structure beats prose. Three high-value spots in technical docs:

1. Architecture Overviews

Show how components connect. A flowchart beats a paragraph of "Service A calls Service B, which then queries Database C."

```mermaid flowchart LR Client --> APIGateway APIGateway --> AuthService APIGateway --> PaymentService PaymentService --> Database PaymentService --> WebhookQueue WebhookQueue --> Merchant ```

That's six lines of text that replace a 150-word explanation and a screenshot you'd have to redraw every time the architecture changes.

2. Sequence Diagrams for API Flows

When documenting how a request travels through your system, sequence diagrams are unmatched:

```mermaid sequenceDiagram participant C as Client participant A as API participant D as Database C->>A: POST /charges A->>D: Insert charge record D-->>A: Success A-->>C: 201 Created ```

Readers see the exact order of operations. No ambiguity. No "wait, does the database write happen before or after the response?"

3. State Diagrams for Entity Lifecycles

If your documentation covers something with states — a payment that moves from "pending" to "captured" to "refunded" — a state diagram makes the transitions obvious:

```mermaid stateDiagram-v2 [*] --> Pending Pending --> Captured Captured --> Refunded Pending --> Failed Failed --> [*] Refunded --> [*] ```

Four lines. Clear transitions. No paragraph required.

Step 5 — Write the Content Around the Structure

Once your headings, TOC, and diagrams are in place, the actual writing gets easier — you're filling in sections, not figuring out structure.

A few practical rules for the writing itself:

Lead with the task, not the concept. Under "Create Charge," start with the request, not a paragraph explaining what a charge is. Readers come to reference docs to do something, not to learn theory.

Show code, then explain. Put the curl example or code snippet first. Then add one or two sentences of context. Reversing this order buries the answer readers came for.

Keep paragraphs short. Three to four sentences max in technical docs. Long blocks of text in a split-pane editor preview look even worse than they do in a word processor — the narrow preview pane turns them into walls.

Step 6 — Review in the Browser, Then Export

The advantage of doing this in a browser markdown editor: you review in the same environment where you wrote. No build step. No "let me generate the site and check."

Scroll through the preview pane. Check three things:

1. TOC links work. Click every entry. Does it jump to the right section? 2. Mermaid diagrams render. Are all your diagrams showing as visuals, not raw code? If one shows as text, check your syntax — Mermaid is strict about indentation and keywords. 3. Heading hierarchy is consistent. No H2 jumping to H4 without an H3 in between. Gaps break the TOC structure.

When everything looks right, export. Most browser markdown editors let you save as .md directly. From there, your file is portable — push it to a GitHub repo, paste it into a docs platform, or convert it to HTML for a static site.

The Workflow That Sticks

The reason most technical documentation rots isn't that people don't want to write it. It's that the writing process was painful, so nobody updates it. Screenshots break. Section numbers drift. Diagrams become stale because redrawing them takes ten minutes.

When you shift to a lightweight browser markdown editor with Mermaid and auto-TOC, the maintenance cost drops dramatically. Updating a diagram means editing one line of text. Adding a section means typing a heading — the TOC handles itself. The entire doc stays in a single .md file you can version-control like code.

Start with one document. Pick the API or tool that needs docs the most. Open your editor, set up the heading structure, drop in a Mermaid flowchart, and let the TOC generate itself. You'll have clean, maintainable documentation in the time it used to take just to configure a documentation platform.