Skip to main content

Tools

The following are the tools we use to generate our documents

  • Docusaurus
  • Mermaid plugin for Docusaurus
  • draw.io diagramming tool.

Docusaurus​

We are using Docusaurus here as it is high extensible. Some of features we are relying on are as follows

  • MDX and React
    • Allows us to import document partials generated from code
    • Allow us to add custom dynamic widgets
  • Additional plugins
    • theme-mermaid enables rendering of mermaid diagrams.

Mermaid​

As our usage of Docusaurus will involve a fair bit of code and design, we will need Mermaid support to generate diagrams to help explain the things we built here. And we can find the information on how to do this here.

The excerpt is as follows.

npm install --save @docusaurus/theme-mermaid
docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {

  ...

  themes: ['@docusaurus/theme-mermaid'],
  // In order for Mermaid code blocks in Markdown to work,
  // you also need to enable the Remark plugin with this option
  markdown: {
    mermaid: true,
  },

  ...
};

export default config;

Fsm2Mermaid​

Draw.io​

Remember to stop and restart our docusaurus service to enable the plugin.

npm start

Draw.io is an established tool to help with drawing of large variety of diagrams.

For diagrams not supported by mermaid, we could use SVG format. Drawio could be used to draw diagrams while embedded inside the SVG file. The limitation of this approach is that we cannot do inline edits of this file. We need to clone locally and to open it with Draw.io and

test diagram from drawio