search

BookStackApp / BookStack

A platform to create documentation/wiki content built with PHP & Laravel
https://www.bookstackapp.com/
MIT License
14.96k stars 1.87k forks source link

[Feature Request] Math & UML #495

Open Zottelchen opened 7 years ago

Zottelchen commented 7 years ago

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 commented 7 years ago

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

Zottelchen commented 7 years ago

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

TBK commented 6 years ago

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

noxify commented 6 years ago

For Mathjax, here the MD / TinyMCE implementation:

DagW commented 6 years ago

+1 for Mermaid!

TBK commented 5 years ago

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

JHenneberg commented 5 years ago

I also would appreciate this very much :)

nicobbg commented 5 years ago

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

ltDan79 commented 5 years ago

+1 :)

brutecode commented 5 years ago

+1 mermaid looks super dope

ThomasF34 commented 5 years ago

+1 for Mermaid features :)

eceforge commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

+1 for Mathjax or KaTeX

Zeigren commented 4 years ago

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 commented 4 years ago

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

ssddanbrown commented 4 years ago

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 commented 4 years ago

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/katex@0.11.1/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/katex@0.11.1/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/katex@0.11.1/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 commented 4 years ago

+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 commented 4 years ago

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

ssddanbrown commented 4 years ago

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

ascii78 commented 4 years ago

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:

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

ascii78 commented 4 years ago

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:

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

davidjgraph commented 4 years ago

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

noahlove commented 4 years ago

+1 this would be an amazing feature

dean-mrack commented 3 years ago

Mermaid or PlantUML is very amazing in Markdown editor +1

MFYDev commented 3 years ago

+1 Really need this feature.

dopoljak commented 3 years ago

+1

Bruno4l commented 3 years ago

+1

cadavre commented 3 years ago

Currently I'm using BookStack in such a way I create Mermaid graph in Live Editor which gives me PNG and I use it as a image. But below I paste source Markdown for future edit purposes. Having it built-in would be wonderful.

PS Having it in such a way with draw.io would albo be wonderful. ;) Currently draw.io once saved is not editable – it hurst, but it's different story. :)

nightsparc commented 3 years ago

Would also love to have Mermaid around :)

PS Having it in such a way with draw.io would albo be wonderful. ;) Currently draw.io once saved is not editable – it hurst, but it's different story. :)

That's not true...you can re-edit any draw.io diagram by just double-clicking on the image in the preview :)

cadavre commented 3 years ago

That's not true...you can re-edit any draw.io diagram by just double-clicking on the image in the preview :)

Oh my... 😅 You just changed my life to better! Thank you! :)

nightsparc commented 3 years ago

Oh my... sweat_smile You just changed my life to better! Thank you! :)

You're welcome :)

paolobasso99 commented 2 years ago

Since I really wanted Latex support I developed a little hack that correctly display math both while viewing and editing a page (using markdown).

Firstly I include Katex in the head:

<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"></script>

Then the following script add the event listeners to correctly displaying latex:

<script>
function renderMath (pageContent) {
    renderMathInElement(pageContent,{
        delimiters: [
            {left: '$$', right: '$$', display: true},
            {left: '$', right: '$', display: false},
            {left: '\\(', right: '\\)', display: false},
            {left: '\\[', right: '\\]', display: true}
        ],
                // It is important to disable throwing errors which causes loops in the editing view
                throwOnError : false
    });
}

// View
document.addEventListener("DOMContentLoaded", () => {
    const pageContent = document.body.getElementsByClassName("page-content");
    if (pageContent.length > 0) {
        renderMath(pageContent[0]);
    }
});

// Markdown edit
document.addEventListener('editor-markdown::setup', () => {
    const markdownDisplay = document.getElementsByClassName("markdown-display")[0];

    markdownDisplay.addEventListener('load', () => {
        const pageContent = markdownDisplay.contentWindow.document.getElementsByClassName("page-content")[0];
        renderMath(pageContent);

        const observer = new MutationObserver((mutationsList, observer) => {
            renderMath(pageContent);
        });
        observer.observe(pageContent, {
            attributes: false,
            childList: true,
            subtree: true
        });
    });
});
</script>

As you can see I use a MutationObserver.

I only use the markdown editor so I have implemented a solution only for that one but using MutationObserver and the editor-tinymce::setup event it should be easy to port this solution to tinymce.

If you ever need to export as pdf or html you could export a markdown file and then convert it using, for example, pandoc which supports the KaTeX syntax.

paolobasso99 commented 2 years ago

Apparently, the little hack I developed does not work anymore on the edit screen.

In particular const pageContent = markdownDisplay.contentWindow.document.getElementsByClassName("page-content")[0]; does not works and the iframe appears to have no source when using the developers tools (I do not understand why that is).

The load element of the iframe is not fired anymore too.

cdrfun commented 2 years ago

Mermaid syntax is supported via diagrams.net https://www.diagrams.net/blog/mermaid-diagrams

dean-mrack commented 2 years ago

awesome, thank you )

Let me make just a little remark. The Mermaid diagram has a clear advantage over PlantULM, that allows you to select a text or search for it on page with diagram. In the implementation diagrams.net an image is formed, as well as silt at PlantUML. That's great, but Mermaid is better in its search capability. But there is also a great https://kroki.io which in my opinion is even more interesting than Mermaid.

cdrfun commented 2 years ago

Yeah, this is a good point and also an issue with the current diagrams implementation apart from using mermaid. Maybe it would be an option to extract all text from the diagram and add it somehow to the document?

tacerus commented 1 year ago

@Zeigren

The included draw.io has support for PlantUML

Is there any information on how to use this? The provided link unfortunately returns a 404. We run PlantUML ourselves and it would be great to integrate it with our BookStack instance.

sceptri commented 1 year ago

Since I really wanted Latex support I developed a little hack that correctly display math both while viewing and editing a page (using markdown).

Firstly I include Katex in the head:

<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"></script>

Then the following script add the event listeners to correctly displaying latex:

<script>
function renderMath (pageContent) {
  renderMathInElement(pageContent,{
      delimiters: [
          {left: '$$', right: '$$', display: true},
          {left: '$', right: '$', display: false},
          {left: '\\(', right: '\\)', display: false},
          {left: '\\[', right: '\\]', display: true}
      ],
                // It is important to disable throwing errors which causes loops in the editing view
                throwOnError : false
  });
}

// View
document.addEventListener("DOMContentLoaded", () => {
  const pageContent = document.body.getElementsByClassName("page-content");
  if (pageContent.length > 0) {
      renderMath(pageContent[0]);
  }
});

// Markdown edit
document.addEventListener('editor-markdown::setup', () => {
  const markdownDisplay = document.getElementsByClassName("markdown-display")[0];

  markdownDisplay.addEventListener('load', () => {
      const pageContent = markdownDisplay.contentWindow.document.getElementsByClassName("page-content")[0];
      renderMath(pageContent);

      const observer = new MutationObserver((mutationsList, observer) => {
          renderMath(pageContent);
      });
      observer.observe(pageContent, {
          attributes: false,
          childList: true,
          subtree: true
      });
  });
});
</script>

As you can see I use a MutationObserver.

I only use the markdown editor so I have implemented a solution only for that one but using MutationObserver and the editor-tinymce::setup event it should be easy to port this solution to tinymce.

If you ever need to export as pdf or html you could export a markdown file and then convert it using, for example, pandoc which supports the KaTeX syntax.

As @paolobasso99 mentioned later, this unfortunately doesn't work. But today I played around with it a lot and it seems I got it working like so:

<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css" integrity="sha384-vKruj+a13U8yHIkAyGgK1J3ArTLzrFGBbBc0tDp4ad/EyewESeXE/Iv67Aj8gKZ0" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.js" integrity="sha384-PwRUT/YqbnEjkZO0zZxNqcxACrXe+j766U2amXcgMg5457rve2Y7I6ZJSm2A0mS4" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>
<script>
function renderMath (pageContent) {
    renderMathInElement(pageContent,{
        delimiters: [
            {left: '$$', right: '$$', display: true},
            {left: '$', right: '$', display: false},
            {left: '\\(', right: '\\)', display: false},
            {left: '\\[', right: '\\]', display: true}
        ],
                // It is important to disable throwing errors which causes loops in the editing view
                throwOnError : false
    });
}

// View
document.addEventListener("DOMContentLoaded", () => {
    const pageContent = document.body.getElementsByClassName("page-content");
    if (pageContent.length > 0) {
        renderMath(pageContent[0]);
    }
    const snippet = document.body.getElementsByClassName("entity-item-snippet");
    if (snippet.length > 0) {
        snippet.forEach(element => renderMath(element));
    }
});

async function asyncRenderMath(pageContent) {
    const result = await renderMath(pageContent);
}

window.addEventListener('load', () => {   
    const markdownDisplay = document.getElementsByClassName("markdown-display")[0];
    const pageContent = markdownDisplay.contentWindow.document.getElementsByClassName("page-content")[0];

    renderMath(pageContent);

    pageContent.addEventListener("DOMSubtreeModified", () => {
        setTimeout(() => {
           asyncRenderMath(pageContent);
        }, 500);
    });
});
</script>

I know it is not the best solution, but it (kinda) works. Hopefully someone finds it useful :smile:

vfosnar commented 1 year ago

+1 for kroki

pada57 commented 8 months ago

+1 for support of UMl as text based

This solution will be much better for developers as can maintain only one place in git their designs and push to bookstack as is without any picture convertion.

Plant or mermaid or both support will be a killer feature

Seems support is available at least on draw.io

https://www.drawio.com/blog/plantuml