Skip to content

Diagrams in Markdown

There are many ways to add diagrams to your Markdown documentation. Here are some popular options and their differences:

Mermaid

Mermaid turns simple text into diagrams like flowcharts and sequence diagrams. It is versatile and integrates seamlessly with Markdown, making it perfect for documentation on GitHub Pages.

  • Easy to use, supports many types of diagrams, works well with GitHub Pages.
  • GitHub Pages can display Mermaid diagrams without extra setup. See GitHub blog post Include diagrams in your Markdown files with Mermaid
  • Mermaid works well with Markdown, making it perfect not only for documentation on GitHub Pages.

To use Mermaid in Material for MkDocs, see Mermaid docs for Diagrams

Examples of Mermaid C4 models

The following diagrams show the architecture of Dokk, a documentation site built with MkDocs and Material theme, and hosted on GitHub Pages.

Note: These diagrams were mindlessly generated by AI and have been humanly checked for syntax errors. The Human is not very impressed, but the purpose here is to show how to use Mermaid for C4 modeling, not to create a perfect architecture diagram.

See the official documentation for Mermaid C4 modeling at mermaid.js.org/syntax/c4.html.

C4Context
    title System Context diagram for Dokk

    Person(user, "User", "A user of the documentation site")
    System(dokk, "Dokk", "Documentation site built with MkDocs and Material theme, hosted on GitHub Pages")

    Rel(user, dokk, "Uses")

    UpdateLayoutConfig($c4ShapeInRow="1", $c4BoundaryInRow="1")
C4Container
    title Container diagram for Dokk

    Person(user, "User", "A user of the documentation site")

    Container(dokk, "Dokk", "MkDocs", "Documentation site built with MkDocs and Material theme, hosted on GitHub Pages")
    Container(githubPages, "GitHub Pages", "GitHub", "Hosting platform for the documentation site")
    Container(devContainer, "Dev Container", "Docker", "Development environment for Dokk")

    Rel(user, dokk, "Uses")
    Rel(user, devContainer, "Develops")
    Rel(dokk, githubPages, "Hosted on")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")
C4Component
    title Component diagram for Dokk

    Container(dokk, "Dokk", "MkDocs", "Documentation site built with MkDocs and Material theme, hosted on GitHub Pages")

    Component(mkdocs, "MkDocs", "Python", "Generates the static site")
    Component(materialTheme, "Material Theme", "Python", "Provides the theme for the site")
    Component(githubPages, "GitHub Pages", "GitHub", "Hosts the generated static site")

    Rel(dokk, mkdocs, "Generates")
    Rel(mkdocs, materialTheme, "Uses")
    Rel(dokk, githubPages, "Hosted on")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")
C4Component
    title Code diagram for Dokk

    Component(mkdocs, "MkDocs", "Python", "Generates the static site")
    Component(config, "Config", "Python", "Handles the configuration for MkDocs")
    Component(theme, "Theme", "Python", "Applies the theme to the site")

    Rel(mkdocs, config, "Uses")
    Rel(mkdocs, theme, "Uses")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

D2

D2 is a modern tool that makes it easy to create diagrams from simple text.

  • Pros: Simple and easy to learn, good for quick diagrams.
  • Cons: May require additional setup to work with GitHub Pages.

PlantUML

PlantUML creates detailed diagrams from plain text descriptions.

  • Pros: Supports a wide range of detailed diagrams, very powerful.
  • Cons: Requires a server or local setup to render diagrams, more complex to integrate with GitHub Pages.

Graphviz

Graphviz creates diagrams from text descriptions.

  • Pros: Powerful and flexible, can create complex diagrams.
  • Cons: May require additional tools and setup to work with GitHub Pages.