L10 Ci Cd Diagrams

title: "CI/CD for Diagrams — Automated Rendering Pipelines" weight: 10 description: "Learn CI/CD integration for diagram-as-code: automated rendering in GitHub Actions, validation, deployment, and ensuring diagrams stay up to date with code changes through automation." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagram-as-code] }

CI/CD for diagrams automates the rendering, validation, and deployment of diagram-as-code files, ensuring diagrams are always up to date and consistent with the current codebase.

In this lesson, you will learn how to set up automated diagram rendering in CI pipelines, validate diagram syntax, fail builds on errors, and deploy diagrams alongside documentation.

What You'll Learn

You will learn to create CI pipelines for diagram rendering, validate syntax automatically, fail builds on diagram errors, and deploy rendered diagrams with documentation builds.

Why It Matters

Manual diagram updates are forgotten during busy sprints. Automated CI pipelines ensure diagrams are rendered on every commit, preventing stale architecture documentation.

Real-World Use

DodaTech's GitHub Actions pipeline renders all Mermaid, PlantUML, and D2 diagrams on every commit. If a diagram has a syntax error, the build fails and the developer must fix it before merging.

name: Render Diagrams
on: [push]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli
      - name: Render Mermaid Diagrams
        run: |
          for f in content/**/*.mmd; do
            mmdc -i "$f" -o "static/diagrams/$(basename $f .mmd).svg"
          done
      - name: Install PlantUML
        run: sudo apt-get install -y plantuml
      - name: Render PlantUML
        run: |
          for f in content/**/*.puml; do
            plantuml -tsvg "$f"
          done

def create_ci_workflow(diagram_tools):
    """Generate a CI workflow configuration for diagram rendering."""
    steps = []
    tools_config = {
        "mermaid": 'npm install -g @mermaid-js/mermaid-cli\nmmdc -i "$file" -o "$output"',
        "plantuml": 'sudo apt-get install -y plantuml\nplantuml -tsvg "$file"',
        "d2": 'curl -fsSL https://d2lang.com/install.sh | sh -s --\nd2 "$file" "$output"',
    }
    for tool in diagram_tools:
        steps.append({
            "tool": tool,
            "command": tools_config.get(tool, ""),
        })
    return steps

workflow = create_ci_workflow(["mermaid", "plantuml", "d2"])
for step in workflow:
    print(f"{step['tool']}: {step['command'][:50]}...")

def validate_diagram_syntax(file_path, tool):
    """Validate diagram syntax without rendering."""
    validators = {
        ".mmd": "npx mmdc -i {file} -o /dev/null 2>&1",
        ".puml": "plantuml -checkonly {file} 2>&1",
        ".d2": "d2 fmt {file} 2>&1 || d2 {file} /dev/null 2>&1",
    }
    ext = "." + file_path.rsplit(".", 1)[-1]
    command = validators.get(ext, "").format(file=file_path)
    return command

def deploy_diagrams(source_dir, target_dir):
    """Copy rendered diagrams to deployment directory."""
    import os, shutil
    if os.path.exists(target_dir):
        shutil.rmtree(target_dir)
    shutil.copytree(source_dir, target_dir)
    return f"Deployed diagrams from {source_dir} to {target_dir}"

print(deploy_diagrams("rendered-diagrams", "static/diagrams"))

Teacher Mindset

Think of CI/CD for diagrams as an automated quality gate. Before a developer's code reaches production, tests must pass. Before a developer's documentation reaches readers, diagrams must render. The same discipline applies. Automate the boring parts. Let machines handle rendering while humans handle the creative work of writing clear diagrams.

Common Mistakes in CI/CD for Diagrams

1. No Validation Step

Rendering without validation produces broken images. Validate syntax before rendering. Fail the build on syntax errors.

2. Not Caching Dependencies

Installing Mermaid CLI or PlantUML on every run wastes minutes. Cache tool installations. Use GitHub Actions cache or Docker images with pre-installed tools.

3. Rendering All Diagrams on Every Commit

For large projects with hundreds of diagrams, incremental rendering saves time. Only re-render diagrams that changed.

4. No Output Verification

A rendered SVG file that is 0 bytes means the render failed silently. Check file sizes and verify output exists.

5. Ignoring Build Warnings

Mermaid warnings about deprecated syntax become errors when the syntax is removed. Treat warnings as errors. Update deprecated syntax proactively.

Practice Questions

1. What is the purpose of CI/CD for diagrams? To automate diagram rendering, validate syntax, and ensure diagrams are always up to date with code changes. CI/CD prevents stale documentation.

2. How do you validate diagram syntax in CI? Use tool-specific validation commands: mmdc -i for Mermaid, plantuml -checkonly for PlantUML, d2 fmt for D2. Check the exit code for errors.

3. How do you handle diagram dependencies in CI? Use Docker containers with pre-installed tools, or cache installations with GitHub Actions cache. Include diagram tools in your build environment setup.

4. What should happen when a diagram has a syntax error? The CI build should fail. The developer must fix the diagram syntax before merging. This enforces diagram quality.

5. Challenge: Set up a GitHub Actions workflow that renders Mermaid and PlantUML diagrams on every push. Include validation, caching, and deployment to a diagrams directory.

FAQ

Mini Project

Set up a GitHub Actions workflow for your documentation project. Include Mermaid rendering, syntax validation, and deployment to a static directory. Test with a commit that introduces a diagram syntax error and verify the build fails.

What's Next

Version Control Diagrams in the next lesson.