=== CanaryBlue Diagrams for Mermaid ===
Contributors: canaryblue
Tags: mermaid, diagram, flowchart, gutenberg, block
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.3
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create Mermaid diagrams in Gutenberg with a live preview, four themes and local front-end rendering.

== Description ==

CanaryBlue Diagrams for Mermaid adds a Mermaid Diagram block to the WordPress editor. Enter Mermaid syntax, see a debounced live preview, choose a theme, and publish an accessible SVG diagram without depending on an external CDN.

Mermaid is an independent open-source project. CanaryBlue Diagrams for Mermaid is developed by CanaryBlue and is not affiliated with or endorsed by the Mermaid project.

Features:

* Live Mermaid preview in the block editor.
* Matching front-end rendering from the saved Mermaid source.
* Default, Neutral, Dark and Forest themes.
* An editable accessible label for screen readers.
* Wide and full alignment plus WordPress spacing controls.
* Readable source fallback if JavaScript is unavailable or rendering fails.
* Mermaid 12.2.0 bundled locally with strict security mode.
* A capability-gated Mermaid administration page with version, documentation and support details.

Documentation: https://canaryblue.org/docs/public/diagrams/

Support: https://wordpress.org/support/plugin/canaryblue-diagrams-for-mermaid

Source code: https://forge.canaryblue.org/CanaryBlue-Public/Diagrams-Free

Mermaid syntax reference: https://mermaid.js.org/intro/syntax-reference.html

The Free edition is supported through the WordPress.org forum and does not include a service-level agreement.

== Installation ==

= From your WordPress dashboard =

1. Go to Plugins > Add New Plugin and search for "CanaryBlue Diagrams".
2. Choose Install Now, then Activate.

= Creating your first diagram =

1. In the block editor, add the Mermaid Diagram block.
2. Enter Mermaid syntax. The preview renders as you type.
3. Choose a theme, and set an accessible label, in the block sidebar.

= Installing manually =

If your site cannot install from the Plugin Directory — behind a firewall, or where plugin installation is managed centrally — download the ZIP from https://wordpress.org/plugins/canaryblue-diagrams-for-mermaid/ and use Plugins > Add New Plugin > Upload Plugin.

= Where to find everything else =

Open CanaryBlue Diagrams in the WordPress admin menu for documentation, support and version information.

Full installation guide: https://canaryblue.org/docs/public/diagrams/

== Frequently Asked Questions ==

= Does the plugin load Mermaid from a CDN? =

No. Mermaid 12.2.0 is bundled in the plugin and rendered locally in the visitor's browser.

= Which Mermaid themes are available? =

The block includes Default, Neutral, Dark and Forest.

= Which browsers can draw the diagrams? =

Mermaid 12 needs a browser that understands ES2024. In practice that means Safari 17.4 or later, and a current version of Chrome, Edge or Firefox. On an older browser the diagram is not drawn and the saved Mermaid source stays readable on the page, exactly as it does when JavaScript is unavailable.

= My published diagrams look different after updating to 1.3.0. Why? =

Mermaid 12 draws diagrams with a different layout engine and a different visual style than Mermaid 11. Your diagrams have not been edited and their source is unchanged, but flowcharts, state diagrams and block diagrams are laid out and spaced differently. The theme you chose on each block is still the theme being used.

= What happens when Mermaid syntax is invalid? =

The editor reports the rendering error. On the front end, the saved Mermaid source remains available as a readable fallback.

= The diagram looks right in the editor, but the published page shows the code instead =

This is almost always a caching or performance plugin that minifies or combines JavaScript. Doing so serves a copy of this plugin's script from that plugin's own cache folder, and the files Mermaid needs to draw each diagram type are then looked for in that folder, where they are not. The block falls back to showing the diagram source, which is the code on the page.

In your caching or performance plugin, exclude `canaryblue-diagrams-for-mermaid` from JavaScript minification and combining, then clear its cache. In WP-Optimize this is under Minify > JavaScript. If your site runs more than one such plugin, exclude it in each.

The editor is unaffected because those plugins do not usually minify editor scripts, which is why the preview looks correct while the page does not.

If the diagram has emoji in its labels, and the page sometimes draws it correctly, see the next entry instead.

= A diagram with emoji in its labels shows the code instead, and only sometimes =

Update to 1.4.0 or later, which fixes this.

Before 1.4.0, WordPress's own emoji support could rewrite the emoji inside a diagram while it was still being drawn. That broke the diagram and left its code on the page.

It was intermittent in a way that made it hard to recognise. The first view of a page often drew the diagram correctly and a refresh then showed the code, because what happened depended on whether WordPress's emoji files were already in the browser's cache.

If you cannot update yet, taking the emoji out of the diagram's labels avoids it. Writing them as Mermaid character codes such as `#128100;` does not, because those become the same characters before the diagram is drawn.

= My diagram draws correctly, but the emoji in it are missing =

Update to 1.4.0 or later.

Before 1.4.0, WordPress's emoji support could replace the emoji in a diagram's saved source with images before the plugin read that source. The diagram was then drawn without them. It looked perfectly normal and reported no error, so the only sign was that something you wrote was not there.

This has the same cause as the entry above and the same fix. Your diagrams do not need editing; they are drawn from the source you already saved.

= How do I make a diagram accessible? =

Use the Accessible label setting in the block sidebar to provide a short description that is applied to the rendered SVG.

= Where can I get help? =

Post in the support forum at https://wordpress.org/support/plugin/canaryblue-diagrams-for-mermaid. That is the support route for the free plugin, and answers there help the next person with the same question.

Plugin documentation is at https://canaryblue.org/docs/public/diagrams/.

CanaryBlue Diagrams Pro customers can also use https://canaryblue.org/contact/ or email support@canaryblue.org. Use those routes for anything that should not be discussed in public, such as a site address, a licence key, or anyone else's data.

= Where is the source code? =

The plugin package ships its own human-readable source in the `src/` directory, alongside the `package.json` that pins the build toolchain. The canonical repository, including build configuration, tests and release workflows, is at https://forge.canaryblue.org/CanaryBlue-Public/Diagrams-Free. The source is licensed under GPLv2 or later.

= How do I report a security issue? =

Do not report a suspected vulnerability in public, including in the WordPress.org support forum and in any public issue tracker. Email support@canaryblue.org or use https://canaryblue.org/contact/ with the subject "Security report: CanaryBlue Diagrams for Mermaid".

== Screenshots ==

1. A Mermaid diagram in the block editor, with the preview updating as you type.
2. Adding the Mermaid Diagram block from the inserter.
3. Four built-in themes - Default, Neutral, Dark and Forest.
4. An accessible label describes the diagram for screen-reader users.
5. The published page, rendered in the visitor's browser with no external requests.
6. When the syntax is wrong, the editor says so and the diagram source stays readable.

== Development ==

This plugin uses a modern JavaScript build pipeline (Webpack + npm, through @wordpress/scripts) to generate the compiled assets found in the `build/` directory.

To comply with the WordPress.org requirement for human-readable code, the uncompiled source is included in this package:

* `src/` — the readable ES modules, block metadata and stylesheets used to generate the production bundles in `build/`.
* `package.json` — the pinned build toolchain (@wordpress/scripts 32.6.0) and the pinned Mermaid version.

Building from source, from the directory containing `package.json`:
  npm install
  npm run build

The complete repository, including build configuration, tests, contribution guidance and release workflows, is publicly available at:

https://forge.canaryblue.org/CanaryBlue-Public/Diagrams-Free

The only third-party library in the compiled output is Mermaid 12.2.0, which is MIT licensed. Its notice is in `THIRD-PARTY-NOTICES.txt` and its own unminified source is published by the Mermaid project at:

https://github.com/mermaid-js/mermaid

The exact bundled version is tagged there as `mermaid@12.2.0`:

https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4012.2.0

== Changelog ==

= 1.4.0 =
* Raise the minimum supported PHP version from 8.1 to 8.3. Sites running PHP below 8.3 will not be offered this update.
* PHP 8.3.36 or 8.4.27 or later is recommended, as earlier releases are affected by CVE-2026-109618 and CVE-2026-109619.
* Correct the PHP requirement stated in the bundled README, which still said 7.4.
* Fix diagrams with emoji in their labels appearing as their own code on published pages. WordPress's emoji support could rewrite the emoji inside a diagram while it was still being drawn, which broke the diagram; the emoji are now kept out of it until it has been drawn, and put back before it reaches the page. The symptom was intermittent, because it depended on whether WordPress's emoji files were already in the browser's cache.
* Fix emoji disappearing from a diagram with no error shown. WordPress's emoji support could replace the emoji in a diagram's saved source with images before the plugin read that source, so the diagram was drawn without them, looked normal and still reported success. The source is now read in a way that recovers them.
* Stop showing the diagram source for a moment before the diagram replaces it. The source is the fallback for a page where the diagram cannot be drawn, so it is still shown whenever JavaScript does not run or the render fails; it is now hidden as soon as the diagram is on the page, rather than after the diagram has also been measured and framed.
* Add Frequently Asked Questions entries for these symptoms.
* No change to blocks, saved content, block attributes or PHP APIs.

= 1.3.0 =
* Update the bundled Mermaid from 11.16.1 to 12.2.0, and adopt Mermaid 12's own rendering defaults.
* Diagrams already published are not edited and their saved source is unchanged, but Mermaid 12 draws them differently. Flowcharts and state diagrams are routed and spaced differently; block diagrams are wider. Mindmap, sequence, class, entity-relationship, Gantt, pie, journey, quadrant, requirement, timeline, xychart, packet, git graph and architecture diagrams are substantially unchanged.
* Default, Neutral, Dark and Forest continue to work, and the theme chosen on each block is still the theme used.
* Raise the minimum browser to one supporting ES2024: Safari 17.4 or later, and a current version of Chrome, Edge or Firefox. This is a Mermaid 12 requirement, not a choice made here.
* The plugin package grows from about 1.1 MB to about 1.6 MB, because Mermaid 12 bundles the ELK layout engine it now uses. Mermaid is still bundled locally and no diagram is rendered through a CDN.
* Remove the correction that centred labels inside circular mindmap nodes. Mermaid 11 placed those labels incorrectly and the plugin moved them back; Mermaid 12 places them correctly, so continuing to move them pushed long labels out of their own node and made them unreadable.
* Add readme entries covering the appearance change and the browser requirement.
* No change to blocks, saved content, block attributes or PHP APIs.

= 1.2.1 =
* Fix diagrams appearing as their own code on published pages where a caching or performance plugin minifies or combines JavaScript. The plugin now states where its own files are, instead of working it out from wherever its script happens to be served, so moving that script no longer stops diagrams being drawn.
* Say what to do when a diagram cannot be drawn because part of the plugin did not load, rather than reporting an internal file name.
* Add a Frequently Asked Questions entry for the same symptom.
* No change to blocks, saved content, block attributes, PHP APIs or browser rendering.

= 1.2.0 =
* Raise the minimum supported PHP version from 7.4 to 8.1. Sites running PHP below 8.1 will not be offered this update.
* First release published through the WordPress.org Plugin Directory.
* Route free support to the WordPress.org support forum, and say plainly which routes are for Pro customers and which are not.
* Rewrite the Installation section for installation from the Plugin Directory, and add a manual route for sites that cannot install from it.
* Replace ten deep documentation links on the About page with the documentation index, so the page stops going stale every time a guide is renamed.
* Describe the Pro edition as it actually ships today, rather than as it stood several releases ago.
* Add screenshots and their captions for the Plugin Directory listing.
* Include the admin menu icon and the CanaryBlue logo in the production package; the menu icon had never been packaged.
* No change to blocks, saved content, block attributes, PHP APIs or browser rendering.

= 1.1.2 =
* Correct the documentation address declared in the plugin header, the readme and the About page; the previous address returned a 404.
* Include the plugin's human-readable source and its build manifest in the distributed package, alongside the generated assets.
* Name the bundled Mermaid 11.16.1 upstream source and its exact release tag in the readme and the third-party notices.
* Update the canonical source repository address after its rename to CanaryBlue-Public/Diagrams-Free.
* No change to blocks, saved content, block attributes, PHP APIs or browser rendering.

= 1.1.1 =
* Resolve WordPress Plugin Check warnings ahead of the first WordPress.org submission.
* Package the complete Mermaid 11.16.1 legal attribution as `THIRD-PARTY-NOTICES.txt` instead of an unexpected root Markdown file.
* Shorten the 1.1.0 Upgrade Notice to remain within WordPress.org's 300-character limit.
* Invoke the prefixed administration menu action with a statically visible hook name while preserving its public name and arguments.

= 1.1.0 =
* Rename the plugin to CanaryBlue Diagrams for Mermaid before its first WordPress.org submission.
* Adopt the canonical `canaryblue-diagrams-for-mermaid` slug, folder, archive, main-file and text-domain identity.
* Preserve existing Mermaid Diagram blocks, saved markup, block attributes, PHP APIs and browser rendering APIs.
* Add explicit notice that the plugin is developed independently by CanaryBlue and is not affiliated with or endorsed by the Mermaid project.

= 1.0.2 =
* Correct circular mindmap label vertical alignment by neutralizing Mermaid's label offset.
* Apply the correction in both the Gutenberg preview and published-page rendering API paths.

= 1.0.1 =
* Correct centre alignment of native SVG labels in circular mindmap nodes.

= 1.0.0 =
* First production-ready release.
* Synchronize plugin, package, block and WordPress readme version metadata.
* Publish definitive plugin and author links, support contacts and documentation links.
* Include explicit Mermaid 11.16.1 MIT license attribution in the production package.
* Strengthen release metadata and canonical archive validation.

= 0.1.2 =
* Add CanaryBlue branding, definitive documentation and support links to the About page.
* Display the installed plugin version and bundled Mermaid version.
* Verify the CanaryBlue logo and Mermaid version in production archives.

= 0.1.1 =
* Add the capability-gated Mermaid admin menu and About page.
* Correct the production archive so it has one installable mermaid-for-wordpress root directory.

= 0.1.0 =
* Initial Gutenberg block with live preview, four themes, accessible labels and resilient source fallback.

== Upgrade Notice ==

= 1.4.0 =
Requires PHP 8.3 or later; sites below that will not be offered this release. Use PHP 8.3.36, 8.4.27 or later to stay clear of the PHP2Shell vulnerabilities. Also fixes diagrams with emoji in their labels showing as code, or drawing without the emoji at all.

= 1.3.0 =
Updates bundled Mermaid from 11.16.1 to 12.2.0. Your diagrams are not edited, but Mermaid 12 draws them differently: flowcharts, state diagrams and block diagrams will look different on published pages. Needs Safari 17.4 or later, or a browser of similar age.

= 1.2.1 =
Fixes diagrams appearing as code on published pages where a caching or performance plugin minifies JavaScript. If you excluded this plugin from minification as a workaround, you can remove that exclusion after updating. No change to blocks, saved content, APIs or rendering.

= 1.2.0 =
This release requires PHP 8.1 or later; sites below that will not be offered it. Support for the free plugin moves to the WordPress.org forum. No change to blocks, saved content, APIs or rendering.

= 1.1.2 =
Corrects the documentation address declared by the plugin and ships the plugin's own source alongside the built assets. No change to blocks, saved content, APIs or rendering.

= 1.1.1 =
Submission-readiness update: resolves WordPress Plugin Check warnings without changing blocks, saved content, APIs or rendering. The complete bundled Mermaid 11.16.1 licence remains included in THIRD-PARTY-NOTICES.txt.

= 1.1.0 =
This release changes the plugin folder and main-file identity; existing blocks and diagrams remain compatible. After confirming 1.1.0 is active, deactivate and remove any manually installed pre-1.1.0 Mermaid for WordPress copy. WordPress may initially show both plugins.

= 1.0.2 =
Corrects circular mindmap label vertical alignment in both the Gutenberg preview and published pages.

= 1.0.1 =
Corrects text alignment in circular mindmap nodes while preserving existing diagrams and Mermaid rendering settings.

= 1.0.0 =
Production-ready release with synchronized metadata, definitive documentation and support links, and explicit bundled-library attribution. Existing Mermaid Diagram blocks are retained unchanged.

== Third-Party Services ==

The plugin does not contact a third-party service to render diagrams. Mermaid 12.2.0 is bundled locally and is licensed under the MIT License. See THIRD-PARTY-NOTICES.txt in the plugin package.

