Reviewed mermaid viewer hack

[hacks] / content / mermaid-viewer / index.md

diff --git a/content/mermaid-viewer/index.md b/content/mermaid-viewer/index.md
index 754fdb4345b2589af224b5fa9102902cbc2a6b3f..3001c89796403f4a786254b1121ae7cacdecf717 100644 (file)
--- a/content/mermaid-viewer/index.md
+++ b/content/mermaid-viewer/index.md
@@ -1,13 +1,12 @@
 +++
-title = "Mermaid viewer"
+title = "Mermaid Viewer"
 author = "@Alexander-Wilms"
-date = 2024-07-16T00:00:00Z
-updated = 2024-07-16T00:00:00Z
-tested = "v25.05"
+date = 2025-06-27T00:00:00Z
+updated = 2025-06-27T00:00:00Z
+tested = "v25.05.1"
 +++
 
-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).
-It automatically detects `pre code` blocks with the class `language-mermaid` and replaces them with a feature-rich viewer:
+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:
 
 ````markdown
 ```mermaid
@@ -20,7 +19,8 @@ flowchart TD
 ```
 ````
 
-The viewer provides the following functionalities:
+On page view, the hack will replace these "mermaid" code blocks with a feature-rich viewer. The viewer provides the following functionalities:
+
 - **Pan and Zoom:** Pan the diagram by clicking and dragging, zoom using the mouse wheel or use dedicated buttons for both.
 - **Interaction Toggle:** Toggle manual interaction (pan/zoom) on or off using a lock/unlock button so it doesn't interfere with scrolling the page.
 - **Reset Zoom:** Reset the diagram to its default zoom level and centered position.
@@ -31,10 +31,16 @@ The viewer provides the following functionalities:
 #### Considerations
 
 - This relies on JavaScript to parse and render content on page load.
-- This loads the Mermaid.js library from `cdn.jsdelivr.net` and Font Awesome icons from `cdnjs.cloudflare.com`.
+- This loads both the Mermaid JavaScript library and Font Awesome icons from external Cloudflare based CDN URLs.
+- Diagrams will not be rendered when using system export options.
 - There is no live preview of the *interactive viewer features* while editing the page content.
 - 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.
+- Since the viewer is rendered after page load, it may result in extra visual jumping of page content during page load.
 
 #### Code
 
-{{<hack file="head.html" type="head">}}
+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:
+
+{{<hack file="layouts/parts/base-body-start.blade.php" type="visual">}}
+{{<hack file="public/mermaid-viewer.css" type="visual">}}
+{{<hack file="public/mermaid-viewer.js" type="visual">}}