T02: Embedding in Markdown and Documentation

6.2.1 Why Embedding Matters

Mermaid becomes truly powerful when embedded directly into documentation workflows.

Instead of:

Creating diagrams separately
Exporting images
Uploading static files

You embed diagram code directly into:

README files
Technical documentation
Wikis
Knowledge bases
Static site generators

This enables:

Version control
Automatic rendering
Consistent documentation
Zero manual exports

Diagram-as-Code only reaches its full potential when integrated into documentation systems.

6.2.2 Basic Markdown Embedding

The standard syntax for embedding Mermaid in Markdown is:

```mermaid
flowchart TD
    A[Start] --> B[End]
```

When rendered in supported platforms, this automatically becomes a diagram.

6.2.3 Embedding in GitHub

GitHub natively supports Mermaid inside Markdown.

Example README snippet:

## System Architecture

```mermaid
flowchart LR
    User --> API
    API --> Database
```

Steps:

Create README.md
Add Mermaid block
Commit and push
GitHub renders automatically

No additional configuration required.

6.2.4 Embedding in GitLab

GitLab also supports Mermaid blocks natively.

Usage is identical:

```mermaid
sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response
```

This works in:

Project README
Wiki pages
Merge requests

6.2.5 Embedding in Static Site Generators

Popular documentation tools support Mermaid with minimal setup:

Docusaurus
MkDocs
VitePress
Hugo
VuePress

Example: Docusaurus configuration

Install:

npm install @docusaurus/theme-mermaid

Enable in config:

themes: ['@docusaurus/theme-mermaid'],
markdown: {
  mermaid: true,
},

Then use:

```mermaid
flowchart TD
    A --> B
```

Now diagrams render automatically during build.

6.2.6 Embedding in HTML Documentation

If you are building raw HTML documentation:

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>

<div class="mermaid">
flowchart TD
    A[Start] --> B[End]
</div>

</body>
</html>

This works for:

Internal portals
Product documentation
Engineering dashboards

6.2.7 Embedding in Obsidian and Notion

Obsidian

Enable Mermaid plugin
Use standard code block:

```mermaid
classDiagram
    User --> Order
```

Notion

Notion supports Mermaid inside code blocks labeled mermaid.

These integrations are ideal for:

Personal knowledge management
Internal documentation
Brainstorming

6.2.8 Rendering in CI/CD Pipelines

You can render Mermaid diagrams automatically during build.

Example using Mermaid CLI:

mmdc -i architecture.mmd -o architecture.svg

In GitHub Actions:

- name: Generate Diagrams
  run: |
    npm install -g @mermaid-js/mermaid-cli
    mmdc -i docs/system.mmd -o docs/system.svg

This ensures:

Always up-to-date diagrams
No manual image exports
Fully automated documentation pipeline

6.2.9 Embedding Diagrams in Technical Documentation

Example: API documentation page.

# Authentication Flow

The following sequence diagram illustrates login interaction:

```mermaid
sequenceDiagram
    participant User
    participant WebApp
    participant AuthService

    User->>WebApp: Submit Credentials
    WebApp->>AuthService: Validate
    AuthService-->>WebApp: Result
    WebApp-->>User: Response
```

Benefits:

Diagram lives next to explanation
Version controlled with text
Always in sync with code updates

6.2.10 Embedding Large Architectures

For large systems, consider:

Storing .mmd files separately
Importing into documentation
Splitting large diagrams into smaller modules

Example project structure:

docs/
  architecture/
    system.mmd
    auth.mmd
    payments.mmd

This improves maintainability.

6.2.11 Using Markdown Variables and Templates

In some documentation systems, you can dynamically inject content.

Example:

```mermaid
flowchart LR
    {{serviceA}} --> {{serviceB}}
```

Templating allows:

Environment-specific diagrams
Automated architecture updates
Dynamic documentation generation

6.2.12 Security Considerations

When embedding in web environments:

Avoid allowing arbitrary Mermaid input from untrusted users
Use strict CSP policies
Validate content if user-generated

Mermaid is rendering code — treat it carefully in public-facing systems.

6.2.13 Common Embedding Mistakes

Forgetting mermaid language tag
Incorrect indentation inside Markdown
Using unsupported platforms
Mixing tabs and spaces
Forgetting to enable Mermaid in documentation config

Incorrect:

```flowchart
A --> B


Correct:

````markdown
```mermaid
flowchart TD
    A --> B


---

# 6.2.14 Refactoring Exercise (Hands-On)

Start with plain Markdown:

```
System architecture:
User -> API -> DB
```

Refactor to embedded Mermaid:

````markdown
System architecture:

```mermaid
flowchart LR
    User --> API --> DB
```

Observe:

Improved clarity
Professional documentation appearance
Structural visualization

6.2.15 Best Practices for Documentation Integration

Keep diagrams close to explanatory text
Version control everything
Avoid exporting static images when possible
Break large diagrams into modular sections
Use consistent styling across documentation

Documentation should evolve with code.

6.2.16 Key Takeaways

Embedding Mermaid in Markdown and documentation systems enables:

Diagram-as-Code workflows
Version-controlled architecture
CI/CD rendering automation
Seamless integration into static sites
Reduced documentation drift

Mermaid’s true strength lies not only in diagram creation — but in how easily it integrates into modern engineering documentation pipelines.

In the next topic, we will explore CLI and CI/CD Integration, where Mermaid becomes part of automated build systems and production workflows.

PreviousT01: Theming and Styling NextT03: CLI and CI/CD Integration

Last updated 1 month ago

hashtag6.2.1 Why Embedding Matters

hashtag6.2.2 Basic Markdown Embedding

hashtag6.2.3 Embedding in GitHub

hashtag6.2.4 Embedding in GitLab

hashtag6.2.5 Embedding in Static Site Generators

hashtag6.2.6 Embedding in HTML Documentation

hashtag6.2.7 Embedding in Obsidian and Notion

hashtagObsidian

hashtagNotion

hashtag6.2.8 Rendering in CI/CD Pipelines

hashtag6.2.9 Embedding Diagrams in Technical Documentation

hashtag6.2.10 Embedding Large Architectures

hashtag6.2.11 Using Markdown Variables and Templates

hashtag6.2.12 Security Considerations

hashtag6.2.13 Common Embedding Mistakes

hashtag6.2.15 Best Practices for Documentation Integration

hashtag6.2.16 Key Takeaways