T03: CLI and CI/CD Integration

6.3.1 Why CLI and CI/CD Integration Matter

When diagrams live only in Markdown, they are useful for documentation. When diagrams are rendered automatically in pipelines, they become:

• Production artifacts

• Version-controlled assets

• Always up-to-date architecture visuals

• Automation-friendly

Integrating Mermaid into CLI tools and CI/CD pipelines enables:

• Automatic SVG/PNG generation

• Documentation site builds

• Architecture snapshots per release

• Zero manual diagram exports

This is where Mermaid transitions from a documentation helper to an engineering workflow tool.

---

6.3.2 Installing Mermaid CLI

Mermaid provides a command-line interface called mmdc.

Install globally:

npm install -g @mermaid-js/mermaid-cli

Verify installation:

mmdc -h

If successful, you can now render diagrams from terminal.

---

6.3.3 Creating a Mermaid File

Create a file:

touch architecture.mmd

Add content:

Save the file.

---

6.3.4 Rendering to SVG

Generate SVG output:

mmdc -i architecture.mmd -o architecture.svg

• -i → input file

• -o → output file

SVG is recommended because:

• Scalable

• Lightweight

• Version-friendly

---

6.3.5 Rendering to PNG

mmdc -i architecture.mmd -o architecture.png

PNG is useful for:

• Slide decks

• Email attachments

• Static documentation exports

---

6.3.6 Using a Configuration File

Create config.json:

{
  "theme": "dark",
  "themeVariables": {
    "primaryColor": "#002b5c",
    "primaryTextColor": "#ffffff"
  }
}

Render using config:

mmdc -i architecture.mmd -o architecture.svg -c config.json

This ensures consistent styling across builds.

---

6.3.7 Batch Rendering Multiple Diagrams

Example directory:

diagrams/
  auth.mmd
  payments.mmd
  orders.mmd

Batch script (Linux/macOS):

for file in diagrams/*.mmd; do
  mmdc -i "$file" -o "${file%.mmd}.svg"
done

Now every .mmd file produces an .svg.

---

6.3.8 Integrating with GitHub Actions

Example workflow:

name: Generate Mermaid Diagrams

on:
  push:
    paths:
      - "diagrams/*.mmd"

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli

      - name: Generate Diagrams
        run: |
          for file in diagrams/*.mmd; do
            mmdc -i "$file" -o "${file%.mmd}.svg"
          done

      - name: Commit Generated Files
        run: |
          git config user.name "github-actions"
          git config user.email "[e-mail]"
          git add diagrams/*.svg
          git commit -m "Auto-generate diagrams" || echo "No changes"
          git push

This workflow:

• Detects changes

• Regenerates diagrams

• Commits updated visuals

Fully automated.

---

6.3.9 Integrating with GitLab CI

Example .gitlab-ci.yml:

generate_diagrams:
  image: node:18
  script:
    - npm install -g @mermaid-js/mermaid-cli
    - for file in diagrams/*.mmd; do mmdc -i "$file" -o "${file%.mmd}.svg"; done
  artifacts:
    paths:
      - diagrams/*.svg

Artifacts store generated diagrams.

---

6.3.10 Integrating with Documentation Builds

For static site generators:

Example: Pre-build step

npm install -g @mermaid-js/mermaid-cli
mmdc -i docs/architecture.mmd -o docs/assets/architecture.svg
npm run build

This ensures:

• Documentation always contains fresh diagrams

• No stale visuals in production

---

6.3.11 Versioning Strategy

Recommended practice:

Store:

• .mmd source files in repository

• Generated .svg optionally committed

• Or generated during build only

Two common strategies:

Strategy A — Commit SVGs

Pros:

• Faster site loads

• No runtime rendering

Cons:

• Larger repository

Strategy B — Generate in CI Only

Pros:

• Smaller repo

• Always fresh

Cons:

• Build dependency on CLI

Choose based on project scale.

---

6.3.12 Rendering for Release Snapshots

You can generate diagrams per release version.

Example:

mmdc -i architecture.mmd -o releases/v1.2.0/architecture.svg

This allows:

• Architecture history tracking

• Visual diffing between versions

• Audit-friendly documentation

---

6.3.13 Performance Considerations

For large diagrams:

• Split into modular .mmd files

• Avoid extremely complex graphs

• Render once during build, not per page load

SVG rendering is efficient, but complexity impacts performance.

---

6.3.14 Security Considerations in CI

If diagrams are generated from:

• User-submitted input

• Dynamic system data

Ensure:

• Sanitization

• Controlled execution environment

• No arbitrary code injection

Mermaid CLI runs in Node — treat it as executable code.

---

6.3.15 Real-World Example — Architecture as Code

Project structure:

project/
  src/
  diagrams/
    system.mmd
    auth.mmd
  .github/workflows/build.yml

Workflow:

1. Developer modifies system.mmd

2. Commit triggers GitHub Action

3. SVG regenerated

4. Documentation auto-updated

5. Release contains architecture snapshot

This is Diagram-as-Code fully operationalized.

---

6.3.16 Hands-On Exercise

Create:

1. A diagrams folder

2. Three .mmd files (flowchart, sequence, class diagram)

3. Install Mermaid CLI

4. Write a shell script to render all files

5. Add a basic GitHub Action to automate rendering

Goal: Build a reproducible diagram pipeline.

---

6.3.17 Common Mistakes

• Forgetting to install CLI globally

• Incorrect file paths in CI

• Not committing changes

• Using inconsistent theme configuration

• Generating diagrams manually instead of automating

Automation eliminates human error.

---

6.3.18 Best Practices

• Store .mmd as source of truth

• Use SVG as primary output

• Automate generation

• Keep themes centralized via config

• Modularize diagrams

• Version major architecture updates

Think of Mermaid files as code artifacts.

---

6.3.19 Key Takeaways

CLI and CI/CD integration enables:

• Automated diagram generation

• Release-based architecture snapshots

• Documentation pipelines

• Scalable diagram maintenance

Mermaid becomes powerful when:

• Embedded in Markdown

• Styled consistently

• Automated in build pipelines

At this stage, you have mastered:

• Flowcharts

• Sequence diagrams

• Class diagrams

• State diagrams

• Gantt charts

• Theming

• Embedding

• Automation

You now understand Mermaid not just as a diagramming tool — but as a fully integrated, version-controlled, automation-ready engineering asset.