Replace PlantUML documentation diagrams with Mermaid

[arturcic]

Summary

• replace PlantUML sequence-diagram generation with Mermaid source generation for documentation scenarios
• embed Mermaid source in the generated documentation and render it client-side with a pinned runtime compatible with GitHub Pages
• migrate the branching-strategy and version-calculation diagrams to .mmd, remove obsolete PNG assets, restore pull-request merge scenarios, and retain PlantUML-inspired styling
• document representative Mainline feature-branch comparisons for GitFlow and GitHub Flow while linking to the complete executable scenarios
• run npm installation, source generation, syntax validation, and runtime staging through Cake documentation targets
• update the documentation workflow triggers and npm caching for the Cake-based Mermaid validation

Motivation

The documentation should not depend on a remote PlantUML rendering service or checked-in rendered diagram artifacts. Keeping Mermaid as the reviewable source and rendering it in the generated site removes that external dependency while keeping local previews and GitHub Pages deployment reproducible through the same Cake build.

The Mainline comparisons show how the same representative branch history produces different versions without duplicating every equivalent workflow diagram.

Verification

• dotnet run/docs.dll --target=GenerateMermaidSources
  • 44 documentation scenario tests passed
  • 13 Mermaid sources generated
• dotnet run/docs.dll --target=ValidateMermaidDiagrams
  • 13 test-generated Mermaid sources verified
  • 14 Mermaid diagrams validated
• dotnet run/docs.dll --target=BuildDocs
• dotnet run/docs.dll --target=PreviewDocs
  • documentation preview built and served successfully
• headless Chrome rendering check of the GitFlow documentation page
• git diff --check

Closes #5108

[Copilot]

Pull request overview

This pull request migrates GitVersion’s documentation diagrams from PlantUML (including a remotely-rendered diagram) to a repository-local Mermaid workflow, making diagram sources and rendered SVGs reproducible and CI-verifiable.

Changes:

• Switched test-generated sequence-diagram output from PlantUML to Mermaid, including updated fixtures and new unit tests.
• Added pinned Mermaid CLI tooling plus scripts to generate and drift-check Mermaid sources and SVG assets.
• Updated documentation pages to reference local Mermaid-rendered SVGs and Mermaid sources instead of remote PlantUML links.

Reviewed changes

Copilot reviewed 30 out of 54 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/GitVersion.Testing/Helpers/ParticipantSanitizer.cs	Updates sanitizer documentation to Mermaid context.
src/GitVersion.Testing/Fixtures/SequenceDiagram.cs	Reimplements sequence-diagram generation for Mermaid syntax/output.
src/GitVersion.Testing/Fixtures/RepositoryFixtureBase.cs	Aligns fixture diagram events with new Mermaid sequence diagram API (destroy/commit).
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs	Writes Mermaid sources for GitHubFlow documentation scenarios.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitFlow.cs	Writes Mermaid sources for GitFlow documentation scenarios.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamples.cs	Updates legacy sample tests to new Destroy(branch, from) signature.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs	New helper to persist .mmd sources from documentation scenario tests.
src/GitVersion.Core.Tests/IntegrationTests/DevelopScenarios.cs	Updates destroy calls to include source participant.
src/GitVersion.Core.Tests/Fixtures/SequenceDiagramTests.cs	Adds unit tests validating Mermaid output formatting and escaping.
package.json	Adds pinned Mermaid CLI dependency and scripts to generate/check diagrams.
docs/scripts/render-mermaid.mjs	New renderer to generate/check deterministic Mermaid SVGs via mmdc.
docs/scripts/generate-mermaid-sources.mjs	New generator/checker to produce .mmd sources by running documentation scenario tests.
docs/mermaid-config.json	Mermaid configuration enabling deterministic IDs and consistent rendering.
docs/input/docs/learn/how-it-works.md	Replaces remote PlantUML image with local SVG and links to Mermaid source.
docs/input/docs/learn/branching-strategies/githubflow/examples.md	Switches examples to .svg and documents the new regen workflow.
docs/input/docs/learn/branching-strategies/gitflow/examples.md	Switches examples to .svg and documents the new regen workflow.
docs/input/docs/learn/branching-strategies/contribute-examples.md	Updates contributor guidance from PlantUML to Mermaid + new commands.
docs/input/docs/img/version-calculation.svg	Adds locally-rendered Mermaid SVG asset for version calculation diagram.
docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.svg	Adds locally-rendered Mermaid SVG for GitHubFlow release example.
docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.svg	Adds locally-rendered Mermaid SVG for GitHubFlow feature example.
docs/input/docs/img/DocumentationSamplesForGitFlow_ReleaseBranch.svg	Adds locally-rendered Mermaid SVG for GitFlow release example.
docs/diagrams/version-calculation.mmd	Adds Mermaid source for version calculation diagram.
docs/diagrams/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitHubFlow_ReleaseBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitHubFlow_FeatureBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_VersionedReleaseBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_VersionedHotfixBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_SupportBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_ReleaseBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_HotfixBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_FeatureFromMainBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_FeatureFromDevelopBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_DevelopBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
.github/workflows/docs.yml	Adds npm ci + Mermaid drift verification to the docs workflow.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:27

• generate-mermaid-sources.mjs hard-codes platform-specific absolute paths to the dotnet host. This will fail for contributors and self-hosted runners where .NET is installed in a different location (even though dotnet is typically available on PATH and via DOTNET_ROOT). Prefer resolving via env vars and/or falling back to dotnet so the docs tooling is portable.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:27

• The script hard-codes platform-specific absolute paths to the dotnet host and fails if the SDK is installed elsewhere (e.g., macOS ARM Homebrew uses /opt/homebrew/..., custom DOTNET_ROOT, or any PATH-only install). This makes npm run diagrams:sources unnecessarily brittle for contributors and nonstandard CI runners.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/scripts/render-mermaid.mjs:77

• When spawnSync fails to launch the Mermaid CLI (e.g., missing node_modules or wrong platform binary), result.status is typically null and result.error contains the real cause (ENOENT, EACCES, etc.). The current check treats this as a generic non-zero exit and throws an error that hides the underlying problem, making contributor troubleshooting harder.

Consider explicitly handling result.error before checking status, and include the executable path in the message.
docs/scripts/generate-mermaid-sources.mjs:62

• Similar to render-mermaid.mjs, if spawnSync cannot start dotnet (bad DOTNET_ROOT, missing PATH entry), the real failure details are in result.error while result.status is usually null. The current code throws a generic exit-code error, which can obscure the root cause.

Handle result.error explicitly and include the resolved executable path to make failures actionable.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/GitVersion.Testing/Fixtures/RepositoryFixtureBase.cs:76

• Remove now writes the diagram "destroy/delete" event before actually removing the branch from the repository. If Repository.Branches.Remove(branch) throws (e.g., missing branch), the generated diagram will incorrectly record a deletion that never happened. Capture the source branch name first, remove the branch, then append the diagram destruction.
  src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs:17
• The .mmd output written here depends on Environment.NewLine used by StringBuilder.AppendLine, which can differ across platforms. Because the drift-check compares files byte-for-byte, this can cause false failures or noisy diffs when regenerating on different OSes. Normalize line endings before writing so the committed Mermaid sources remain deterministic.
  docs/scripts/generate-mermaid-sources.mjs:81
• The --check path compares generated .mmd files byte-for-byte (Buffer.equals). That is brittle: line endings (LF vs CRLF) and other benign encoding differences can trigger false "stale" failures. Read the files as UTF-8 text and normalize line endings before comparing so drift checks stay stable across environments.
  docs/scripts/render-mermaid.mjs:41
• --check currently creates docs/input/docs/img/ even when the command is only verifying drift. This introduces an avoidable working-tree side effect (and can leave an empty directory behind in fresh clones). Consider only creating the output directory when generating, not when checking.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs:16

• DocumentationDiagramWriter writes the diagram text with platform-specific line endings (from StringBuilder.AppendLine). Because the repo enforces LF checkouts via .gitattributes (* text=auto eol=lf), generating/checking Mermaid sources on Windows will produce CRLF output and make npm run diagrams:sources:check report stale .mmd files. Normalize to \n before writing so the generated sources are OS-independent.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:74

• The generator script hard-codes generatedFiles.length !== 11, which will start failing any time a new documentation scenario is added (even if the new .mmd is correctly generated and committed). Instead of a fixed count, compare the generated file list to the committed docs/diagrams/DocumentationSamplesFor*.mmd list and fail on missing/extra files.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/docs.yml:114

• npm ci was added in the validate job without any npm cache restore in that job. Since GitHub Actions jobs run on fresh runners, the npm cache step in prepare does not benefit validate, so this will likely increase CI time and network usage for every docs PR. Consider adding an npm cache step (or actions/setup-node with npm caching) in validate before running npm ci.

      - name: Install npm dependencies
        run: npm ci # NOSONAR -- Puppeteer's pinned postinstall installs Mermaid CLI's browser.

      - name: Verify Mermaid diagrams
        run: npm run diagrams:check

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 41 out of 70 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/GitVersion.Testing/Fixtures/SequenceDiagram.cs:173

• EscapeText replaces semicolons with #59;, which is not a valid HTML entity and will render literally as “#59;” in the generated SVG/text. If the goal is to avoid Mermaid parsing issues while preserving the displayed semicolon, use a real entity like &#59; (or ;).
  src/GitVersion.Testing/Fixtures/SequenceDiagram.cs:63
• Mermaid participant aliases should be quoted to safely handle branch names / labels that include characters Mermaid treats specially (e.g., /, spaces). Without quotes, participant {id} as {label} may fail to parse for some branch names.
  build/docs/Utilities/Mermaid.cs:96
• Linked issue #5108 acceptance criteria calls out committing and validating reproducible rendered artifacts (SVG drift checks). ValidateMermaidSyntax currently only parses .mmd sources; nothing in this build utility generates/compares SVGs, so CI won’t catch rendering regressions or drift beyond syntax changes. Consider either (1) adding an SVG render/compare step (e.g., using a pinned mermaid CLI) or (2) updating the issue/acceptance criteria to explicitly document the client-side-only rendering approach.

        public void ValidateMermaidSyntax()
        {
            var validationScript = context.MakeAbsolute(ValidationScript);
            var arguments = new ProcessArgumentBuilder();
            arguments.AppendQuoted(validationScript.FullPath);

[mergify]

Thank you @arturcic for your contribution!