BookStack Code Mirror - hacks/blob - content/mermaid-viewer/index.md

   1 +++
   2 title = "Mermaid viewer"
   3 author = "@Alexander-Wilms"
   4 date = 2024-07-16T00:00:00Z
   5 updated = 2024-07-16T00:00:00Z
   6 tested = "v25.05"
   7 +++
   8
   9 This hack enables interactive Mermaid diagrams to be rendered within a page on BookStack. The Mermaid code itself can be written and edited using either BookStack's WYSIWYG editor by creating a code block and assigning it the language "mermaid" or the Markdown editor (using standard ` ```mermaid ... ``` ` code fences).
  10 It automatically detects `pre code` blocks with the class `language-mermaid` and replaces them with a feature-rich viewer:
  11
  12 ````markdown
  13 ```mermaid
  14 flowchart TD
  15     A[Christmas] -->|Get money| B(Go shopping)
  16     B --> C{Let me think}
  17     C -->|One| D[Laptop]
  18     C -->|Two| E[iPhone]
  19     C -->|Three| F[fa:fa-car Car]
  20 ```
  21 ````
  22
  23 The viewer provides the following functionalities:
  24 - **Pan and Zoom:** Pan the diagram by clicking and dragging, zoom using the mouse wheel or use dedicated buttons for both.
  25 - **Interaction Toggle:** Toggle manual interaction (pan/zoom) on or off using a lock/unlock button so it doesn't interfere with scrolling the page.
  26 - **Reset Zoom:** Reset the diagram to its default zoom level and centered position.
  27 - **Copy Code:** Copy the underlying Mermaid code to the clipboard.
  28 - **Font Awesome Icons:** Use Font Awesome icons directly within the Mermaid diagram syntax.
  29 - **Text selection:** When interaction is disabled, text can be selected and copied.
  30
  31 #### Considerations
  32
  33 - This relies on JavaScript to parse and render content on page load.
  34 - This loads the Mermaid.js library from `cdn.jsdelivr.net` and Font Awesome icons from `cdnjs.cloudflare.com`.
  35 - There is no live preview of the *interactive viewer features* while editing the page content.
  36 - The viewer injects its own CSS for styling. While designed to be self-contained, there's a minor possibility of style interactions with highly customized BookStack themes.
  37
  38 #### Code
  39
  40 {{<hack file="head.html" type="head">}}