Search

How to enable flow diagrams in Github from gh-pages:

  • github pages are served by jekyll and more information can be found in the following document github pages & jekyll

  • flow and sequence diagrams are popular mean to provide a graphical overview of processes. Since FAIRification recipes are processes at the core, it is a strong requirement to enhance the recipes with such graphical overview

  • mermaid is a javascript library allowing to generate diagrams, charts, graphs or flows from markdown-like text via javascript.

    • mermaid documentation is extensive, see here
    • mermaid is compatible with jekyll via a gem plugin
  • The following steps need to be performed to enable a github repository to serve mermaid defined diagrams.

    1. install the jekyll mermaid plugin:

      To do so, open a terminal, and run the following command in the suitable virtual environment

      > gem install jekyll-mermaid
      
    2. edit the the Jekyll _config.yml file:

      • declare the plugin to the Jekyll _config.yml file by adding the following line:

        gems: [jekyll-mermaid]
        

        see the Jekyll documentation for more installation options.

      • add the path the mermaid javascript library. Note this should be the distribution .js file, not the source files.

      • The distribution file for the mermaid javascript library can be obtained from:

        mermaid.js
          mermaid.core.js
          mermaid.min.js
        

        By default, the path the js library is set in the _config.file to js_url: /assets/js. Therefore, to indicate the path to the mermaid.js library, simply add the following:

        mermaid:
         src: '/js/mermaid.js'
         src_config: '/js/config.js'
        
      • in order to have mermaid to work with jekyll on github, you need to obtain the library from the following site. mermaid library distribution

        curl -O https://unpkg.com/mermaid@7.1.0/dist/mermaid.js
        curl -O https://unpkg.com/mermaid@7.1.0/dist/mermaid.core.js
        curl -O https://unpkg.com/mermaid@7.1.0/dist/mermaid.min.js
        
3. edit the `head.html` template under `_include` folder

Since Jekyll build every page served by include the head.html template, it will also load by default the mermaid library,
    which is then able to process the relevant section defining the diagrams:
    ```
    <!-- using mermaid for rendering Diagram and flow chart -->
        <script src="/cookbook-dev/assets/js/mermaid.min.js"></script>
        <script>mermaid.initialize({startOnLoad:true});</script>
        ```

4. testing:

    - Does this state diagram work?

stateDiagram [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*]

    - Does this Gantt chart display?  

gantt title A Gantt Diagram dateFormat YYYY-MM-DD section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d another task : 24d

    - Does this flowchart display?

graph LR; A["input data"]-->B["conversion to open format"]; A["input data"]-->C["automatic annotation"]:::box; B["conversion to open format"]-->D(("output data")); C["automatic annotation"]-->D(("output data")); style A fill:#FF5733,stroke:#333,stroke-width:2px style D fill:#0A749B,stroke:#333,stroke-width:2px classDef box fill:#2a9fc9,color:#fff;
if you cannot view the Gantt chart or the State Diagram, it means you are running an outdated version of the mermaid distribution. try upgrading by download the files from here