How to add flow charts, equations and interactive graphs to Markdown documents

Have you come across a scenario that you would like to include some simple diagrams or equations in a Markdown document? If this is a one-off thing, what you could do is to use Power Point or an online generator, save the diagram as image and put it in your article. The drawback of this approach is the background color may not match your article and it’s time consuming to make changes.

Markdown extensions are additional functionalities provided by third party software that enrich the content of markdown documents. We will go over three commonly used ones that many you may use when the occasion comes.

Flow chart & diagrams - Mermaid

Mermaid is a javascript-based markdown extension that let you create diagrams and visualizations using text and code. With just a few lines of code, you can create flowchart, sequence diagram, Gantt chart, pie chart and more.

It can be seamlessly integrated with Markdown. You call it by using fenced code (```) with the mermaid label. For example

    ```mermaid
    erDiagram
        CUSTOMER ||--o{ ORDER : places
        ORDER ||--|{ LINE-ITEM : contains
        CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
    ``` 

Turns to

Mermaid has been around for some time and have received wide support from the markdown community. For example, Github’s build-in markdown engine and note-taking app Joplin supports Mermaid out of the box. You can learn more about how to use Mermaid and try out their live editor.

Math equations

Are you a student or a researcher who needs to take math notes? Many markdown editors or engines support Latex-style equations. It turns any code starts and ends with $ or $$ to equations.

For example

$$
I = \int_a^b f(x) dx
$$

turns to

Here is a nice cheat sheet to get you started. If you are looking for adding math support to your website, a common math engine is MathJax. Enabling it is as easy as adding a few lines to the header file of your site.

Interactive table and graphs - R Markdown

Writers who need to generate documents with advanced interactive plots and tables can rely on R Markdown. R Markdown provides seamless integration of R programming language, a popular statistical language for data analysis, to Markdown. It is especially beneficial to markdown users who already know the R language.

For example, code fence like

    ```{r}
    ggplot(cars, aes(speed, dist)) + geom_point()
    ```

runs the R codes within and produces the following plot.

Using R libraries rCharts or plotly, writer can easily create interactive graphs embedded in the rendered webpage, all defined by a single R Markdown text file. Readers who are interested in seeing a demo can check out this gallery.

R Markdown documents are usually edited using R Studio, a popular IDE for the R programming language. You can create as little as a single document or as large as a website. Since rendering notes can involve heavy computation (You can run any R codes inside the fence!), the usage of R markdown is limited to local notes, websites or cloud computing environments.

Summary

Using the basic and extended markdown syntax gets you covered for writing basic documents. For advanced usages like adding flow chart, gnatt chart, equations and interactive graph, you can consider the add-ons described in this article. Hope this helps!

One last thing…

Do you want to make your life easier when writing markdown documents on your phone?

Try our free Markdown keyboard on iPhone!

Download in App Store