This is extension for Diplodoc platform which adds support for Mermaid diagrams.
Extension contains some parts:
- Prepared Mermaid runtime
- MarkdownIt transform plugin
- React hook_and_component for smart control of Mermaid
Attach plugin to transformer
import mermaid from '@diplodoc/mermaid-extension';
import transform from '@diplodoc/transform';
const {result} = await transform(`
\`\`\`mermaid
graph TD
A[Christmas] -->|Get money| B(Go shopping)
\`\`\`
`, {
plugins: [
mermaid.transform({ bundle: false })
]
});Add mermaid runtime to your final page
<html>
<head>
<!-- Read more about '_assets/mermaid-extension.js' in 'MarkdownIt transform plugin' section -->
<script src="_assets/mermaid-extension.js" async />
</head>
<body style="background: #000">
${result.html}
<script>
// Read more about 'mermaidJsonp' in 'Prepared Mermaid runtime' section
window.mermaidJsonp = window.mermaidJsonp || [];
window.mermaidJsonp.push((mermaid) => {
mermaid.initialize({ theme: 'dark' });
mermaid.run();
});
</script>
</body>
</html>The problem with Mermaid is that it has big bundle size.
The most expected behavior is loading it asynchronously.
But if we want to disable Mermaid's startOnLoad option, then we don't know when the Mermaid will be initialized.
Prepared Mermaid runtime designed to solve this problem.
We disable Mermaid's startOnLoad option to precise control render step.
Then we add mermaidJsonp global callback to handle Mermaid's loading.
Also, we limit exposed Mermaid API by two methods:
-
initialize- configure mermaid before next render -
run- start diagrams rendering
Usage example:
window.mermaidJsonp = window.mermaidJsonp || [];
// This callback will be called when runtime is loaded
window.mermaidJsonp.push((mermaid) => {
mermaid.initialize({ theme: 'dark' });
mermaid.run();
});
// You can configure more that one callback
window.mermaidJsonp.push((mermaid) => {
console.log('Render diagrams');
});Exposed mermaid.initialize method has extra configuration options:
-
zoom- Enable diagram zoom and explore feature. Can be boolean or object with inner props.
(Default: false)
-
showMenu- Show navigation menu.
(Default: false) -
bindKeys- Enablewasdcontrols.
Usew/a/s/dto explore diagram,e/qto zoom in/out andrto reset diagram position.
(Default: false) -
maximumScale- Maximum zoom scale.
(Default: 5) -
resetOnBlur- Reeset diagram position on outher click.
(Default: false)
-
Plugin for @diplodoc/transform package.
Configuration:
-
runtime- name of runtime script which will be exposed in resultsscriptsection.
(Default:_assets/mermaid-extension.js) -
bundle- boolean flag to enable/disable copying of bundled runtime to target directory.
Where target directore is<transformer output option>/<plugin runtime option>
Default: true -
classes- additional classes which will be added to Mermaid's diagrams.
Example:my-own-class and-other-class
Simplifies Mermaid control with react
import React from 'react'
import { transform } from '@diplodoc/transform'
import mermaid from '@diplodoc/mermaid-extension/plugin'
import { MermaidRuntime } from '@diplodoc/mermaid-extension/react'
const MERMAID_RUNTIME = 'extension:mermaid';
const Doc: React.FC = ({ content }) => {
const result = transform(content, {
plugins: [
// Initialize plugin for client/server rendering
mermaid.transform({
// Do not touch file system
bundle: false,
// Set custom runtime name for searching in result scripts
runtime: MERMAID_RUNTIME
})
]
})
// Load mermaid only if one or more diagram should be rendered
if (result.script.includes(MERMAID_RUNTIME)) {
// Load oversized mermaid runtime asyncronously
import('@diplodoc/mermaid-extension/runtime')
}
return <div dangerouslySetInnerHTML={{ __html: result.html }} />
}
export const App: React.FC = ({ theme }) => {
return <>
<Doc content={`
\`\`\`mermaid
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
\`\`\`
`}/>
<MermaidRuntime
zoom={{
showMenu: true,
bindKeys: true,
resetOnBlur: true,
}}
/>
</>
}