* ob-mermaid

Generate [[https://mermaidjs.github.io/][mermaid]] diagrams using org-mode, org-babel and [[https://github.com/mermaid-js/mermaid-cli][mermaid-cli]].

* Setup

If you use [[https://github.com/syl20bnr/spacemacs][Spacemacs]], use the [[https://github.com/arnm/mermaid-layer][mermaid Spacemacs layer]].

1. Install package from [[https://melpa.org/#/getting-started][Melpa]]
2. Install [[https://github.com/mermaid-js/mermaid-cli][mermaid-cli]]
3. Ensure =mmdc= (the mermaid-cli executable) is available in your PATH, or specify its full path:
   #+begin_src elisp
   ;; If mmdc is in your PATH, this is optional:
   (setq ob-mermaid-cli-path "mmdc")
   ;; Or specify the full path if needed:
   ;; (setq ob-mermaid-cli-path "/your-installation-path/node_modules/.bin/mmdc")
   #+end_src
4. Add =mermaid= to =org-babel-load-languages= (along with any other languages you use):
   #+begin_src elisp
   (org-babel-do-load-languages
       'org-babel-load-languages
       '((mermaid . t)
         (scheme . t)
         (your-other-langs . t)))
   #+end_src
5. Open =org-mode= buffer and create an =org-babel= source block:
   #+begin_src org
     ,#+begin_src mermaid :file test.png
     sequenceDiagram
      A-->B: Works!
     ,#+end_src
   #+end_src
   #+begin_src mermaid :file test.png
   sequenceDiagram
    A-->B: Works!
   #+end_src
6. Export the =org-mode= document or invoke =org-babel-execute-src-block= (e.g. with =C-c C-c= on a block) to generate the diagram.

* Supported properties

=file= - Output file. It should be either svg, png or pdf.

=width= - Width of the page. Optional.

=height= - Height of the page. Optional.

=scale= - Scale factor of the page. Optional.

=theme= - Theme of the chart, could be default, forest, dark or neutral. Optional.

=background-color= - Background color. Example: transparent, red, '#F0F0F0'. Optional.

=mermaid-config-file= - JSON configuration file for mermaid. Optional.

=css-file= - CSS file for the page. Optional.

=puppeteer-config-file= - JSON configuration file for puppeteer. Optional.

=pdf-fit= - Scale PDF to fit chart. Optional.

=cmdline= - Additional command line arguments to pass to mmdc. Optional.

* Customization

=ob-mermaid-cli-path= - Path to the =mmdc= executable. If =nil=, searches =exec-path=.

=ob-mermaid-default-config-file= - Default mermaid configuration file used when no =:mermaid-config-file= header argument is specified. Useful for setting global defaults.

** SVG Text Rendering in Emacs

By default, mermaid uses [[https://mermaid.js.org/config/schema-docs/config-defs-flowchart-diagram-config.html#htmllabels][HTML labels]] (=<foreignObject>=) in SVG output, which Emacs cannot render. To display text properly in SVG diagrams within Emacs, disable HTML labels via a config file:

1. Create a config file (or use the included =mermaid-config-emacs.json=):
   #+begin_src json
   { "htmlLabels": false, "flowchart": { "htmlLabels": false } }
   #+end_src

2. Set the default config in your Emacs init:
   #+begin_src elisp
   (setq ob-mermaid-default-config-file "/path/to/mermaid-config-emacs.json")
   #+end_src

Alternatively, use the =:mermaid-config-file= header argument per-block.

* Testing

** Automated Batch Test

To run all test diagrams and verify outputs:

#+begin_src shell
./dev-test.sh batch
#+end_src

This will:
- Execute all Mermaid code blocks in =test-example.org=
- Generate output files (PNG, SVG, PDF) for each block
- Report which files were created or missing

Clean up all generated test files with:

#+begin_src shell
./dev-test.sh clean
#+end_src

** Manual/Interactive Test

To open Emacs with the test environment and test interactively:

#+begin_src shell
./dev-test.sh interactive
#+end_src

This will open Emacs with =test-example.org= loaded. Place the cursor on any Mermaid code block and press =C-c C-c= to execute and generate the diagram.

** Note

Test outputs (e.g., =test-*.png=, =test-*.svg=, =test-*.pdf=) and Emacs backup files are git-ignored and cleaned by the script.