Draw diagrams from markdown within ReDoc page #266

avkonst · 2017-05-15T23:12:39Z

I have discovered needs to embed various diagrams within the documentation page rendered by the ReDoc. Currently I generate pictures from PlantUML text and hope to refer to these pictures from the markdown text embedded within the swagger specification, provided to the ReDoc. The problem is that the pictures need to be saved and served from somewhere and could get dis-synchronized with the documentation eventually, because the documentation content ends up in different places.

Instead, it would be great to have a way to render diagrams within the ReDoc page from markdown text embedded within the swagger specification. Something similar to this: http://support.typora.io/Draw-Diagrams-With-Markdown/

Is it valid idea? or I am taking some non-advised approach? If valid, would this feature be possible for implementation?

avkonst · 2017-05-15T23:17:00Z

The last diagram example on this page http://jumly.tmtk.net/ is sort of what diagrams I am trying to draw..

RomanHotsiy · 2017-05-17T11:45:29Z

@avkonst thanks for this feature request.
But I'm not sure if this should be the part of ReDoc core. My concerns are following:

there are a lot of diagram rendering engines and if we stick with some specific one, it won't fit all the users
not everyone needs diagrams and adding this to ReDoc core will make js bundle bigger

But I see your use case and I have an idea of how we can cover it:
ReDoc can have an option called markdownCompiler or a set of hooks before/afterMarkdownRender so you can add any diagram rendering engine you want + it won't be limited to diagram generation.
It can be even packed in something like ReDoc plugin 🎁 😀

What do you think?

avkonst · 2017-05-17T21:36:43Z

Hi,

Thanks for the proposal. Maybe hooks/plugins is good feature to have, keep this in mind, but I am not very much dependent on this now. I have solved the problem by inserting a picture link into markdown, and the picture link points out to my backend which generates pictures from text. It allowed me to write documentation in separate markdown editor and still have pictures in preview in the editor. I have not tried it yet to deploy to ReDoc, but as long as the markdown renderer you use in ReDoc can insert SVG and PNG pictures, it should be all good as it is now.

Thanks

webwurst · 2017-05-20T15:47:40Z

Sounds good, I would vote for a plugin for mermaid :)

foriequal0 · 2020-05-20T05:51:22Z

For those who want mermaid anyway, I've made a hacky way to render it.

    mermaid.initialize({startOnLoad: false});
    let id = 0;
    Redoc.init(url, {
        ...configs,
        theme: {
            extensionsHook: (name, props) => {
                if (name !== "Markdown" || props.html === undefined) return "";
                var markdown = document.createElement("div");
                markdown.innerHTML = props.html;
                var mermaidNodes = markdown.querySelectorAll("pre > code.language-mermaid");
                for (const mermaidNode of mermaidNodes) {
                    mermaid.render(`mermaid-${id++}`, mermaidNode.textContent, svg => {
                        mermaidNode.parentNode.outerHTML = svg;
                    });
                }
                props.dangerouslySetInnerHTML.__html = markdown.innerHTML;

                return "";
            }
        }
    }, container);

dcopso · 2022-05-14T21:52:36Z

If you're generating static docs using redoc-cli build, here are the changes to the template file that must be made for mermaid diagrams to be rendered (tested with OpenAPI 3.0.3 spec on redoc-cli 0.13.13):

Add the following code snippet to <head>:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
     mermaid.initialize({startOnLoad: true});
 </script>

Add the following snippet between {{redocHTML}} and </body>:

<script>
 let renderedMermaidId = 0;
 const nextId = () => {
     renderedMermaidId++;
     return renderedMermaidId;
 };
 const renderMermaidDiagrams = () => {
     let mermaidNodes = document.querySelectorAll("pre > code.language-mermaid");
     for (const nv of mermaidNodes) {
         let nextIdz = `mermaid-${nextId()}`;
         let codz = nv.textContent;
         mermaid.render(nextIdz, codz, svg => nv.parentNode.outerHTML = svg)
     }
 };
 renderMermaidDiagrams();
</script>

Invoke build:

npx redoc-cli build -t template.hbs myapi.yaml

Gyunikuchan · 2023-08-22T03:59:56Z

With Mermaid v10's breaking change and its dependence on async/await, I've only been able to get it to work by waiting for Redoc to finish rendering.
https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0
Does anyone know of a better way to implement this?

<body>
<div id="redoc"></div>

<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
<script type="module">
	import mermaid from "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs";
	mermaid.initialize({ startOnLoad: true });

	Redoc.init("./docs/swagger.json", {}, document.getElementById("redoc"), async () => {
		let id = 0;
		const mermaidNodes = document.getElementById("redoc").querySelectorAll("pre > code.language-mermaid");
		for (const mermaidNode of mermaidNodes) {
			const { svg } = await mermaid.render(`mermaid-${id++}`, mermaidNode.textContent);
			mermaidNode.parentNode.outerHTML = svg;
		}
	});
</script>
</body>

RomanHotsiy added the feature label May 17, 2017

ZsZs mentioned this issue Aug 6, 2019

What is the best way to render vendor extenstions? #1004

Closed

devova mentioned this issue Jan 12, 2022

Support MermaidJS diagrams in Alternative API Docs fastapi/fastapi#4418

Closed

AlexVarchuk mentioned this issue Sep 6, 2022

Embed mermaid or plantuml renderer #1459

Closed

grahamegee mentioned this issue May 4, 2023

Render mermaid embedded within swagger/openapi rohit-gohri/redocusaurus#293

Open

lornajane added Type: Enhancement and removed feature labels Jul 28, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Draw diagrams from markdown within ReDoc page #266

Draw diagrams from markdown within ReDoc page #266

avkonst commented May 15, 2017

avkonst commented May 15, 2017

RomanHotsiy commented May 17, 2017

avkonst commented May 17, 2017

webwurst commented May 20, 2017 •

edited

Loading

foriequal0 commented May 20, 2020

dcopso commented May 14, 2022

Gyunikuchan commented Aug 22, 2023 •

edited

Loading

Draw diagrams from markdown within ReDoc page #266

Draw diagrams from markdown within ReDoc page #266

Comments

avkonst commented May 15, 2017

avkonst commented May 15, 2017

RomanHotsiy commented May 17, 2017

avkonst commented May 17, 2017

webwurst commented May 20, 2017 • edited Loading

foriequal0 commented May 20, 2020

dcopso commented May 14, 2022

Gyunikuchan commented Aug 22, 2023 • edited Loading

webwurst commented May 20, 2017 •

edited

Loading

Gyunikuchan commented Aug 22, 2023 •

edited

Loading