Bookstack: [Feature Request] Math & UML

[Zottelchen]

Desired Feature: Math & UML

I would really like a simple way to write down Math and UML. There are enough libaries which support Markdown and WYSIWYG (at least Math, not sure about UML). Also if Math is going to be included please don't forget an easy way to paste special symbols.

[noxify]

For the UML part, do you mean something like this?

• https://github.com/plantuml/plantuml / http://plantuml.com/tinymce
• https://github.com/knsv/mermaid

[Zottelchen]

Yes, exactly. Both seem to give enough options to explain a process visually.

[TBK]

For the math part of your feature request would https://www.mathjax.org/ suffice?

[noxify]

For Mathjax, here the MD / TinyMCE implementation:

• https://hiltmon.com/blog/2017/01/28/mathjax-in-markdown/
• https://github.com/SoftwareMansion/tinymceMathjax

[DagW]

+1 for Mermaid!

[TBK]

@ssddanbrown could this be a v0.27.0 target? 🙏

[JHenneberg]

I also would appreciate this very much :)

[nicobbg]

Mermaid is available in Gitlab and is easy to use. It would be great to have this feature in Bookstack as well.

[ltDan79]

+1 :)

[brutecode]

+1 mermaid looks super dope

[ThomasF34]

+1 for Mermaid features :)

[eceforge]

For the math side of this might I recommend KaTeX https://katex.org/ instead of mathjax -- it's significantly faster and has no dependencies. I've had partial success in fact simply adding the required javascript include to the customer header section of bookstack. The problem comes when attempting to bind the auto-rendering to a javascript event as it seems to break the image insertion as described in #1588

[Lerke]

Another +1 from me. Having embedded UML support via Mermaid or PlantUML instead of having to render it locally and upload would be a great feature!

[gkostkowski]

+1 for Mathjax or KaTeX

[Zeigren]

Another +1 from me. Having embedded UML support via Mermaid or PlantUML instead of having to render it locally and upload would be a great feature!

The included draw.io has support for PlantUML

[kwm1800]

+1 Seriously need this support. A lot of stuffs cannot be written well without math equations.

[ssddanbrown]

I'll probably consider Math as part of the "Editor Alignment & Review" on the roadmap.

If you need something to get by for now, it is possible to insert math via the draw.io integration as described in my comment here:
https://github.com/BookStackApp/BookStack/issues/639#issuecomment-597112337

For markdown editor users, markdown is converted to HTML on the front-end using markdown-it. Looks like there's a few math based markdown-it plugins out there. We fire some events for the editors for people to "hook" into. Details of this can be found here:
https://www.bookstackapp.com/docs/admin/hacking-bookstack/#bookstack-editor-events

You may be able to use a plugin and the above editor hooks to implement this for your own system. An example of doing this for a different markdown-it plugin can be seen here:
https://github.com/BookStackApp/BookStack/issues/1671#issuecomment-607480496

Note, any custmomizations like this are out-of-support so could get broken in future updates.

[eceforge]

So I have been successful in adding KaTeX rendering with just a simple addition to the custom header. This code snippet works only on the main content of an entry so it won't work in the editor or in page titles etc. I did that on purpose because the KaTeX auto-render plugin has some unintended effects when run on the parts of the DOM that include the add-image icon in the editor.

I'm no javscript expert -- feel free to suggest changes, I just couldn't stand not having math in my wiki pages.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">

<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>

<!-- To automatically render math in text elements, include the auto-render extension: -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"></script>
<script>
        var katexRenderFilter = function katexRenderFilter () {
    var content = document.body.getElementsByClassName("page-content");
    if (content.length > 0) {
        renderMathInElement(content[0], 
        {
            delimiters: 
            [
            {left: "$$", right: "$$", display: true},
            {left: "$", right: "$", display: false},
            {left: "\\(", right: "\\)", display: false},
            {left: "\\[", right: "\\]", display: true}
            ]
        }
        );
    }
    }
    document.addEventListener("DOMContentLoaded", katexRenderFilter);
</script>

The process of writing math would be a lot easier I think if we included the "preview" plugin for the tinyMCE GUI editor, I haven't gotten around to re-building the assets for bookstack to include that plugin though. So as of now you have to write the math in latex, and save the page to get it to render. The primary problem with just enabling it in editor is if you enable it then proceed to save the rendered math you get issues in the finished page. So either we need a button to "un-render" the math before the save or the preview function. Maybe a good use of the the new editor hooks?

[coffeepenbit]

+1 I would _really_ appreciate this feature. Right now I'm resorting to writing an equation and taking a screenshot of it.

[Bart-van-Ingen]

+1 this would make bookstack an even better contender to confluence for example! the work around with draw.io, just isnt great ...

[ssddanbrown]

Just had a quick review/think about this, Putting down some thoughts so I don't forget them:

• Mermaid and KaTeX seem to be the most requested and both look well supported.
• Both libraries are of considerable size. Mermaid's dist min.js file is at 1.3MB, KaTeX min.css & min.js being around 280kB excluding required fonts. Would need to be considerate in how these are built/loaded.
• Due to the custom syntax and output we won't really be able to revert or use a different library down the line unless they offered great compatibility. That's a pretty harsh one.
• Also due to the custom syntax and output, user content becomes more "Proprietary" to BookStack which is something I've been adamant I want to specifically avoid. Another harsh one.
• Content would really need to be pre-rendered when saved into storage to provide the best experience, so content loads instantly on view (No loading jolt/jank) and so it at least has a chance of rendering on exports, although unlikely via the default DomPDF renderer.
  
  
  
  • Pre-rendering could be done without too much trouble via the WYSWIYG Editor.
  
  
  • Pre-rendering or even just previewing will be trouble in the Markdown editor, Re-rendering live on change will be janky unless we selectively update but that'd take some work.
  
  
  • Pre-rendering requirement prevents causes stronger dependency on browser-side, and means we can't move final MD rendering to server side. Not even sure how we could support this via the API without some node requirement. That's a pain.
  
  
  • Pre-rendering will make jumping between the editors way more of a painful/confusing/tricky experience.
  
  
  • _On seconds thoughts, I don't think we're going to be able to pre-render._
  
  
• Will require effort in updating the editors, as we draw closer to a time we'd be reviewing options to replace the current editors.
• The use-case for math is fairly strong, since it is often used in documentation for certain fields and the alternative option is not math-focused.
• The current use-case for UML/Mermaid is weaker since we now have draw.io which has a lot of overlap and is well-suited to the use-case of multi-ability environments. I can see why those technically inclined may like UML/Mermaid, kind of want to use it myself tbh, but it's focusing on a narrow audience with a custom text syntax, which kind of opposes the idea/spirit of the project.

[ascii78]

Would be nice if we could get some content like drawio from: https://www.mathcha.io. I do not think they are opensource though so that would be a problem, maybe you could get some ideas from it.

Some other nice graphical things would be:

• https://www.geogebra.org/classic
• https://jsxgraph.uni-bayreuth.de/wp/index.html

But tbh. only a little bit of latex like it is in most markdown processors would be enough for me.

[ascii78]

Just noticed that the embedded draw.io app now features math support, even in the bookstack demo. It's under extra's -> mathematical typesetting. It's mathjax and works great:

• https://desk.draw.io/support/solutions/articles/16000032875 (How to use mathematical typesetting?)
• https://app.diagrams.net/#Uhttps%3A%2F%2Fraw.githubusercontent.com%2Fjgraph%2Fdrawio-diagrams%2Fmaster%2Fdiagrams%2Fmath.xml (example)

_"Not available in offline versions of draw.io"_, not sure how that would impact bookstack.

[davidjgraph]

Not available offline is incorrect. Previously, draw didn't have a way to generate client-side PNG if Math was included, but now does.

[noahlove2658]

+1 this would be an amazing feature

[dean-mrack]

Mermaid or PlantUML is very amazing in Markdown editor +1