Embedding Diagrams in Technical Docs — Docusaurus, MkDocs, GitBook & More

Platform Support at a Glance

Not every documentation platform supports every diagram format. Here's the current state of support:

Docusaurus

Docusaurus is the most popular React-based documentation framework. It supports Mermaid natively via @docusaurus/theme-mermaid. For PlantUML, use the community plugin docusaurus-plantuml.

Mermaid in Docusaurus

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};

Once enabled, use fenced code blocks with the mermaid language tag in any Markdown file. Diagrams render client-side with no build step.

Draw.io / Excalidraw in Docusaurus

For Draw.io and Excalidraw diagrams, the most reliable approach is to export them as SVG files and reference them as images. This avoids plugin dependencies and works with any documentation platform.

MkDocs (Material)

MkDocs Material is the most popular Python-based documentation tool. It has excellent diagram support through plugins.

Mermaid in MkDocs

# mkdocs.yml
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

PlantUML in MkDocs

# mkdocs.yml
plugins:
  - plantuml:
      puml_url: https://www.plantuml.com/plantuml/
      output_format: svg

The PlantUML plugin renders diagrams at build time by sending them to a PlantUML server. For offline builds, point puml_url to a local server.

GitBook

GitBook supports Mermaid natively — just use fenced code blocks. For other diagram formats, export to SVG and embed as an image. GitBook's Markdown processor handles inline SVGs well.

Confluence

Confluence has native Draw.io integration (the diagrams.net for Confluence app). For Mermaid and PlantUML, install the respective Marketplace plugins. Note that plugin availability depends on your Confluence plan — Cloud vs. Data Center.

The SVG Fallback Strategy

When a platform doesn't support your diagram format natively, converting to SVG is the universal escape hatch:

• SVG renders in every documentation platform that supports images
• It scales perfectly at any resolution (unlike PNG)
• Text inside SVGs remains searchable in most renderers
• SVG files are text-based, so they diff well in Git

Orriguii Diagram Converter can convert Excalidraw, Draw.io, and Mermaid files to SVG in the browser. For a CI-based approach, see our guide on SVG optimization for the web.

Best Practices

• Keep source files in the repo — Store .mmd, .excalidraw, or .drawio source files alongside your docs. This makes diagrams editable and versionable.
• Automate SVG export in CI — Use a CI step to regenerate SVG files from source diagrams on every commit. This ensures docs always show the latest version.
• Add alt text — Always provide meaningful alt text for diagram images. Screen readers and search engines rely on it.
• One diagram per concept — A diagram that tries to show everything shows nothing. Keep each diagram focused on a single idea.