Markdown Course: Part 3 of 3

Learn how to use Markdown confidently to get your message across.

Table of contents

• Mathematical expressions

• Diagrams

• 3D models

• Maps

• Center align

• Comments

• Collapsable Content

• Subscript

• Superscript

Other Possibilities

In addition to your daily Markdown usage, there are other exciting features that GitHub Markdown can do.

In this section I will give you a brief overview of these.

---

Mathematical Expressions

When GitHub is rendering Mathematical Expressions in Markdown it uses MathJax . Inline single backtics are used with the $ for Mathematical Expressions.

Add $` at the start of the Mathematical Expression and close it with `$:

$`\sqrt{4x-1}+(1+x)^3`$

This will render the result:

---

Diagrams

GitHub Markdown, like the tool AsciiDoctor, support diagrams directly in Markdown. Why is this important? Diagrams are great, but there are some challenges:

• Everyone uses a different tool to create diagrams;

• Binary files in the git repo are terrible to be tracked by version control - one pixel change and the whole file is re-tracked (plus no one knows what the actually change is);

• It can be unclear who in the team might have the original file to edit the diagram.

This is where Mermaid comes in. It allows us to generate different types of diagrams with code and is very similar to Markdown. The benefit of this is that the diagram content is in the Markdown file in a code block with the type mermaid. Therefore anyone can change it and the changes can be diffed, then this is rendered just like the rest of the Markdown file.

Here is an example of a branching diagram:

NOTE: remember to add the code block with 3 backticks and the type Mermaid.

```mermaid

```

gitGraph:
    commit "Ashish"
    branch newbranch
    checkout newbranch
    commit id:"1111"
    commit tag:"test"
    checkout main
    commit type: HIGHLIGHT
    commit
    merge newbranch
    commit
    branch b2
    commit

Which will render to:

Here is another example for a Sequence Diagram:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

This will render to:

The Mermaid project keeps adding more diagram types all the time, here is what they currently support:

• Flowchart

• Sequence Diagram

• Class Diagram

• State Diagram

• Entity Relationship Diagram

• User Journey

• Gantt

• Pie Chart

• Quadrant Chart

• Requirement Diagram

• Gitgraph (Git) Diagram

• C4 Diagram

• Mindmaps

• Timeline

• Zenuml

• Sankey

• XYChart

• Block Diagram

Learn more on the official Mermaid documentation.

---