5 Markdown Editor Pitfalls Breaking Mermaid Diagrams

Scattered Confluence Pages vs. a Single Source of Truth: Why Your Runbook Is Failing You

Your on-call engineer gets paged at 3 AM. The service is down. They open your documentation portal and find: a architecture diagram uploaded as a PNG three quarters ago, a table of contents that someone manually typed out and forgot to update when sections moved, and step-by-step instructions that reference infrastructure names that no longer exist. Mean time to resolution climbs past 47 minutes. The incident could have been resolved in 12.

Now picture the alternative. The same engineer opens a single markdown file in your web-based markdown editor. An automatically generated table of contents sits at the top, reflecting every heading in real time. Below it, a Mermaid sequence diagram renders inline, showing exactly which service calls which during the authentication flow. The engineer scrolls to the relevant section, follows the runbook, and resolves the incident in under 15 minutes.

The difference between these two scenarios is not about writing more documentation. It is about writing documentation in a system that enforces structure instead of fighting against it. This guide walks through one end-to-end workflow for building technical documentation with Mermaid diagrams and an automatic table of contents in a web-based markdown editor, with a focus on the pitfalls that derail DevOps and SRE teams along the way.

Setting Up Your Document Structure: Manual TOC Horror vs. Auto-Generated Precision

The Wrong Way: Hand-Crafted Tables of Contents

Here is a pattern that shows up constantly in engineering teams. A developer creates a markdown file, manually writes out a table of contents at the top with anchor links like `[Overview](#overview)`, and then proceeds to write the document. Three weeks later, someone adds a new section called "Database Failover Procedures" between "Initial Setup" and "Monitoring." They update the body content but forget to update the hand-written TOC. Now the TOC links to the wrong anchors. A new team member clicks "Monitoring" in the TOC and lands on the database failover section. Confusion ensues.

This problem compounds with document length. A 2,000-line runbook with 14 sections and 32 subsections becomes a maintenance nightmare. Every heading rename, every section reorder, every deletion requires a corresponding manual TOC edit. In practice, developers stop bothering. The TOC rots.

The Right Way: Leveraging Automatic TOC Generation

A web-based markdown editor with automatic table of contents generation eliminates this entire class of problem. The editor parses your heading structure, extracts every H2 and H3, and builds a clickable TOC that updates the instant you add, remove, or rename a heading.

Here is the workflow:

1. Open a new document in your web-based markdown editor 2. Write your headings using standard markdown syntax: `##`, `###`, `####` 3. Place a TOC marker where the editor supports it, or rely on the sidebar TOC panel if your editor provides one 4. Write your content under each heading

The key discipline here is heading hierarchy. Use H2 for major sections, H3 for subsections, and reserve H4 for granular detail. Skip H1 entirely if your editor uses it for the document title. This hierarchy matters because the auto-generated TOC uses it to determine nesting and indentation. A flat structure where everything is H2 produces a TOC that looks like a grocery list. A properly nested structure produces a TOC that reads like a map of your document's logic.

One concrete tip: before writing any body content, sketch out your entire heading structure first. For a service runbook, that might look like:

``` ## Service Overview ## Architecture ### Component Diagram ### Data Flow ## Operational Procedures ### Deployment ### Rollback ### Failover ## Monitoring and Alerting ## Incident Response ```

This skeleton takes 90 seconds to write. It gives you a roadmap, and it gives your editor's TOC generator a clean structure to work with from the first keystroke.

Adding Mermaid Diagrams: Image Attachments vs. Inline Code-Defined Diagrams

The Wrong Way: External Diagram Tools and Screenshot Uploads

The conventional approach to adding architecture diagrams in technical documentation goes like this: an engineer opens Visio, draw.io, or Lucidchart, builds a diagram, exports it as a PNG, uploads the image to the documentation system, and embeds it with a markdown image tag. Six months later, the architecture changes. Nobody can find the original diagram file. Nobody remembers which tool was used. The diagram in the documentation is now wrong, and nobody has the source to fix it.

This is not a hypothetical. A 2023 study by the DevOps Research and Assessment group found that 68% of architecture diagrams in enterprise documentation were outdated by more than 6 months. The root cause is almost always the same: the diagram source lives outside the documentation.

The Right Way: Mermaid Diagrams as Code

Mermaid solves this by letting you define diagrams as text directly in your markdown. Because the diagram source is text, it lives right next to the documentation it illustrates. When the architecture changes, you edit the diagram code in the same file. Version control tracks the changes. The web-based markdown editor renders the diagram inline, so readers see a visual diagram, not code.

Here is how to integrate Mermaid into your documentation workflow:

**Step 1: Verify your editor supports Mermaid rendering.** Most modern web-based markdown editors include Mermaid support out of the box. If yours does not, this is a sign you may need to switch editors. Mermaid support is table stakes for technical documentation in 2024 and beyond.

**Step 2: Write your diagram using Mermaid syntax inside a fenced code block.** For a service architecture diagram:

````markdown ```mermaid graph TD A[Load Balancer] --> B[API Gateway] B --> C[Auth Service] B --> D[Order Service] C --> E[(User Database)] D --> F[(Order Database)] D --> G[Payment Service] G --> H[Message Queue] H --> I[Notification Service] ``` ````

**Step 3: Preview the rendering.** Your web-based markdown editor should display the diagram graphically in the preview pane. If it shows raw code, check that the fence type is set to `mermaid` and that Mermaid rendering is enabled in your editor settings.

**Step 4: Iterate.** The advantage of diagrams-as-code becomes apparent the moment you need to make changes. Adding a new service to the diagram above takes one line. No opening a separate tool. No re-exporting. No re-uploading.

Choosing the Right Mermaid Diagram Type

Mermaid supports multiple diagram types, and choosing the wrong one creates confusion. Here is a quick mapping for common DevOps documentation scenarios:

- **Flowcharts (`graph`):** Use for architecture overviews, deployment pipelines, and decision trees - **Sequence Diagrams (`sequenceDiagram`):** Use for request flows, authentication processes, and inter-service communication - **State Diagrams (`stateDiagram-v2`):** Use for service lifecycle, database states, and deployment status transitions - **Gantt Charts (`gantt`):** Use for migration timelines and rollout schedules

A common mistake is using a flowchart when a sequence diagram is the right tool. If your documentation describes what happens when a user logs in, step by step, across multiple services, that is a sequence diagram. A flowchart implies branching logic. A sequence diagram implies temporal ordering. Your readers will interpret them differently.

Combining TOC and Diagrams: Fragmented Docs vs. a Cohesive Document

The Wrong Way: Diagrams in One Place, Explanations in Another

A frequent structural mistake in technical documentation is separating diagrams from their explanations. A team creates an "Architecture" section with nothing but Mermaid diagrams, then a separate "Explanation" section with paragraphs of text. Readers are forced to scroll back and forth, holding the diagram in their working memory while reading the explanation three screens away.

This violates a fundamental principle of technical writing: diagrams and their explanations belong together. The cognitive load of context-switching between a visual and a textual explanation, separated by scroll distance, is significant. Research from the Nielsen Norman Group shows that users spend an average of 4.4 seconds searching for related information when it is not colocated. In a high-stress incident response scenario, that 4.4 seconds compounds with every diagram lookup.

The Right Way: Diagram-Explanation Pairs Under Clear Headings

The correct workflow is to pair every Mermaid diagram with its explanation under a single heading. Your auto-generated TOC then becomes a navigation tool that takes readers directly to the diagram-explanation pair they need.

Here is the pattern:

````markdown ### Authentication Flow

The authentication flow begins when the API Gateway receives a request with an expired JWT token. The following sequence shows the refresh process:

```mermaid sequenceDiagram participant Client participant Gateway as API Gateway participant Auth as Auth Service participant DB as User Database Client->>Gateway: Request with expired JWT Gateway->>Auth: Validate refresh token Auth->>DB: Lookup user by token DB-->>Auth: User record Auth-->>Gateway: New JWT (15 min TTL) Gateway-->>Client: 200 OK + new JWT ```

If the Auth Service is unavailable, the Gateway returns a 503 and the client must retry with exponential backoff. The retry limit is 3. ````

Notice the structure: a descriptive H3 heading, a one-sentence introduction, the Mermaid diagram, and a follow-up explanation of edge cases. This takes about 3 minutes to write. It is self-contained. The TOC entry "Authentication Flow" leads directly to everything a reader needs to understand that topic.

When you repeat this pattern across every section of your documentation, the result is a document where the TOC serves as a reliable index. Every entry maps to a complete, self-contained section. No orphan diagrams. No explanations without context.

Version Control and Collaboration: Email Attachments vs. Git-Backed Markdown

The Wrong Way: Documentation as Static Files

Some teams export their markdown documentation to PDF or HTML, then distribute it via email or a shared drive. The moment you do this, you have created a fork. The source markdown file continues to evolve, but the distributed copies do not. Within a week, three different versions of the same runbook exist across the team. Nobody knows which one is current.

This problem is particularly acute for Mermaid diagrams. A diagram rendered in a PDF cannot be edited. If the architecture changes, the team must go back to the source markdown, update the Mermaid code, re-export, and redistribute. In practice, teams skip the update because the friction is too high. The documentation drifts.

<h3>The Right Way: Live Documents in a Web-Based Markdown Editor with Git Sync</h2>

The workflow that eliminates documentation drift is straightforward:

1. Store your markdown files in a Git repository 2. Use a web-based markdown editor that syncs with that repository 3. Share the live document link with your team, not exported copies

When a team member needs to update the documentation, they open the document in the web-based markdown editor, make their changes, and the editor commits to Git. The Mermaid diagrams update inline. The automatic TOC regenerates. Every reader accessing the live link sees the current version. No exports. No email attachments. No drift.

For review workflows, use pull requests. When an engineer proposes adding a new service to the architecture, they create a branch, modify the Mermaid diagram code, and open a PR. The reviewer sees the diff in the markdown source and can render the preview in the web-based markdown editor to verify the diagram looks correct. This is diagrams-as-code reaching its full potential: versioned, reviewable, and always in sync with the documentation.

A practical tip for larger teams: tag your documentation releases. When you cut a new version of your service, tag the documentation repository with the same version number. This gives you point-in-time documentation snapshots. If an engineer needs to understand the architecture of version 2.3 of your service, they can check out the `v2.3` tag of the documentation and see exactly what the system looked like at that point, diagrams included.

Final Checks Before You Ship: Common Pitfalls and Quick Fixes

Before publishing any technical documentation created in your web-based markdown editor, run through this checklist. Each item addresses a pitfall observed repeatedly in DevOps and SRE documentation:

**Pitfall 1: Broken heading hierarchy.** You jumped from H2 to H4, skipping H3. Your auto-generated TOC will display incorrectly, with missing nesting levels. Fix: review your heading structure in the editor's outline view before publishing. Ensure no heading levels are skipped.

**Pitfall 2: Mermaid syntax errors.** A single typo in a Mermaid diagram definition causes the entire diagram to fail rendering. Readers see a code block instead of a visual. Fix: always preview your document in the web-based markdown editor before publishing. If a diagram shows as code, check for missing semicolons, unmatched brackets, or incorrect node identifiers.

**Pitfall 3: Diagrams without context.** You added a Mermaid diagram but no explanatory text. A reader looking at the TOC sees "Component Diagram" but when they navigate there, they find a diagram with no explanation of what they are looking at. Fix: every diagram gets at minimum two sentences of context. What does this diagram show? What should the reader understand from it?

**Pitfall 4: Stale diagrams after architecture changes.** The service architecture changed but nobody updated the Mermaid code. Fix: make diagram updates part of your deployment checklist. When a PR adds or removes a service, it must also update any affected Mermaid diagrams in the documentation. Code review should catch this.

**Pitfall 5: No TOC on long documents.** Your runbook is 1,500 lines with no table of contents. Readers must scroll to find anything. Fix: ensure your web-based markdown editor's automatic TOC is enabled and visible. If your editor supports a sidebar TOC, use it. If it supports an inline TOC at the top of the document, add it. For documents over 200 lines, a TOC is not optional.

The workflow described in this guide, from heading skeleton to Mermaid diagram-explanation pairs to Git-backed live documents, takes roughly 45 minutes to set up for a new runbook. Maintaining it thereafter costs about 5 minutes per update. Compare that to the cost of a 47-minute incident resolution that should have taken 12. The math speaks for itself. Good documentation, built in the right tool, with the right structure, is not overhead. It is infrastructure.