1.0.2

Release Notes: Update from [mermaid] to [source, mermaid] in AsciiDoc

Version: 1.0.2
Release Date: 2025-03-12

Overview

This release updates the AsciiDoc syntax for embedding Mermaid diagrams, changing the previous [mermaid] blocks to [source, mermaid]. This modification ensures better compatibility with Asciidoctor and improves rendering consistency across different environments.

Changes

• Updated Mermaid Syntax:
  • Previous Syntax:

    [mermaid]
    ----
    graph TD
        A --> B
    ----

  • New Syntax:

    [source, mermaid]
    ----
    graph TD
        A --> B
    ----

  • This change aligns with best practices for embedding Mermaid diagrams in AsciiDoc and ensures compatibility with Asciidoctor Diagram.

Benefits

• Improved Rendering:

  • The updated syntax follows the standard AsciiDoc approach for code blocks, reducing the risk of parsing errors.

• Better Compatibility with Asciidoctor Diagram:

  • [source, mermaid] ensures that Mermaid diagrams are recognized as code blocks, preventing inconsistencies in rendering.

• Future-Proofing:

  • This update makes it easier to maintain and extend documentation with other syntax-highlighting or processing tools.

Known Issues

• Some environments may still require the Mermaid CLI (mmdc) for rendering diagrams correctly.
• Ensure that the Asciidoctor Diagram plugin is enabled in your documentation pipeline.

Upgrade Instructions

• If you are using a local Asciidoctor setup, make sure you have the latest version of Asciidoctor Diagram installed:

  gem install asciidoctor-diagram