Doing more with markdown

Markdown allows you to create good-looking documents quickly without needing fancy tools and packages, it is entirely text based. This site is made with markdown. But what about diagrams, equations, charts and videos? In this article we give a quick demonstration of what is possible and show you where to find out about a whole lot more.

Jekyll Spaceship

In our article about starting new projects we used Jekyll to turn simple markdown files into HTML pages. We can extend its capabilities with plugins. The jekyll-spaceship plugin gathers together lots of diagramming capabilities into one place. To add it we change the Gemfile in our Jekyll installation:

# Gemfile
group :jekyll_plugins do
  gem "jekyll-spaceship"
end

and add it to the config file, including telling it where it can put some javascript:

plugins:
  - jekyll-spaceship
mermaid:
  src: 'assets/mermaid.js'

Then restart the server:

$ bundle exec jekyll serve --livereload

Now we have a whole new set of markdown instructions for drawing diagrams. Let’s try it out.

Diagrams

The key to understanding markdown is that you describe what you want and leave the actual generation of the corresponding image to the code that renders the markdown, one of the libraries within the jekyll-spaceship plugin in this case.

In this example we invoke the Mermaid library that jekyll-spaceship make available to us, and according to its syntax we say what title we want, then describe a flowchart laid out from left to right (LR). We tell it we want entities that we refer to as “A”, “B”, “C” and “D” but which show-up in the diagram with the text we provide. We also say how the entities are connected by arrows. We can tell it we want normal arrows (-->), bold arrows (==>), dotted arrows (-.->) or arrows with circles at the end rather than points (--o). Similarly the box shapes can be modified to be plain rectangles ([ ]), rhombi ({ }), or slanted any way you want (/ /, / \, \ \). Arrows can also have text on them. The instructions look a bit cryptic but once you get the hang of it they do make sense.

@startmermaid
---
title: "Writing a blog"
---
flowchart LR
   A[Have an idea] -->|Sleep on it| B{Start writing}
   B --o|Elaborate| C[/Longer article/]
   B ==>|Research| D[/More detail\]
   B -.-> E{{spell check}}
@endmermaid

When run through Jekyll, all that becomes this diagram. Notice how it has taken care of how to space things out, align things etc. It tries to do the right thing so you don’t need to be an illustrator or visual designer.

Maths

You have the full power of $\TeX$ and $\LaTeX$ available. That is a whole subject in itself but suffice to say that if you want mathematical equations in your document, you cannot do better than this.

$$
\int\_a^b f(x)\,dx.
$$
$$
\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}
$$

becomes:

$$ \int_a^b f(x)\,dx. $$ $$ \sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6} $$

There is a great summary here.

Tables: the kitchen sink

You can “draw” an elementary table in markdown with pipes | and dashes --, but you can do a whole lot more:

Different text alignment: centred, left aligned etc
Cells spanning columns
Cells spanning rows
Images within cells
CSS styles applied to elements, an image in this case
Bold text
Multi-line text within a cell
Numbered lists within cells
MathJax forumulae putting $\LaTeX$ in cells.

The example here has all of those things in it somewhere. Can you work it out?

[cell-image]: https://jekyllrb.com/img/octojekyll.png "An exemplary image"
{:image-style: style=";width: 100px;"}

| :                   MathJax \|\| Image                 : |||
| :------------ | :-------- | :----------------------------- |
| Apple         | : Apple : | Apple                          \
| Banana        | Banana    | Banana                         \
| Orange        | Orange    | Orange                         |
| :     Rowspan is 4     : || :        How's it?           : |
| ^^     A. Peach          || 1. ![example][cell-image] {: image-style :}     |
| ^^     B. Orange         || ^^ 2. $I = \int \rho R^{2} dV$ |
| ^^     C. Banana         || **It's OK!**   |

becomes:

MathJax \|\| Image
Apple Banana Orange	Apple Banana Orange	Apple Banana Orange
Rowspan is 4 A. Peach B. Orange C. Banana		How’s it?
		$I = \int \rho R^{2} dV$
		$I = \int \rho R^{2} dV$
		It’s OK!

UML diagrams

Being universal you can model anything in UML: classes, states, sequences, anything. Here we show a simple sequence diagram. It is such a small diagram that we do not need the actor boxes repeated in the footer, so we hide them.

@startuml
  hide footbox
  title UML sequence diagram 
  Bob -> Alice: hello world
@enduml

becomes:

Pie charts:

Hopefully you are getting the idea by now:

@startmermaid
pie title Pets adopted by volunteers
  "Dogs" : 386
  "Cats" : 85
  "Rats" : 35
@endmermain

becomes:

Keep going

jekyll-spaceship bundles several image renderers, each with a lot of functionality. It is worth browsing the documentation just to get an idea of what is possible: