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

   1 +++
   2 title = "Mermaid Viewer"
   3 author = "@Alexander-Wilms"
   4 date = 2025-06-27T00:00:00Z
   5 updated = 2025-06-27T00:00:00Z
   6 tested = "v25.05.1"
   7 +++
   8
   9 This hack enables interactive Mermaid diagrams to be rendered within a page on BookStack. The Mermaid diagram code itself can be written & edited using either BookStack's WYSIWYG editor, by creating a code block and assigning it the language "mermaid", or via the Markdown editor using standard `mermaid` code fences like so:
  10
  11 ````markdown
  12 ```mermaid
  13 flowchart TD
  14     A[Christmas] -->|Get money| B(Go shopping)
  15     B --> C{Let me think}
  16     C -->|One| D[Laptop]
  17     C -->|Two| E[iPhone]
  18     C -->|Three| F[fa:fa-car Car]
  19 ```
  20 ````
  21
  22 On page view, the hack will replace these "mermaid" code blocks with a feature-rich viewer. The viewer provides the following functionalities:
  23
  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 both the Mermaid JavaScript library and Font Awesome icons from external Cloudflare based CDN URLs.
  35 - Diagrams will not be rendered when using system export options.
  36 - There is no live preview of the *interactive viewer features* while editing the page content.
  37 - 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.
  38 - Since the viewer is rendered after page load, it may result in extra visual jumping of page content during page load.
  39
  40 #### Code
  41
  42 This hack makes use of [publicly accessible files](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md#publicly-accessible-files) via the visual theme system so that the required files are only loaded in when potentially required:
  43
  44 {{<hack file="layouts/parts/base-body-start.blade.php" type="visual">}}
  45 {{<hack file="public/mermaid-viewer.css" type="visual">}}
  46 {{<hack file="public/mermaid-viewer.js" type="visual">}}