oam/knowledge base/markdown.md

Markdown

ReadMe's Markdown engine.

Table of contents

1. TODO list
2. Folded content
3. Images
4. Diagrams
   1. Flow chart A.K.A. graph
   2. Sequence diagram
   3. Class diagram
   4. State diagram
   5. Gantt diagram
   6. Pie chart
5. Math
6. Troubleshooting
   1. Escape the backtick character
   2. VS Code and mermaid graph in Markdown preview
7. Further readings
8. Sources

TODO list

Use [ ] after the bullet point or numbered list character to switch them for an empty ballot box, and [x] for a checked one.

1. 1
2. 2
   • a

• Point 3

Folded content

Use a <details> HTML tag:

<details>
  <summary>Fold/Open</summary>
  Folded content
</details>

Images

Add an image:

![description](path/to.image)
![description][reference name]

Control width and height:

<img src="./cat.png" width=300px height=200px />

Align in the center:

<div align="center">![sleep-cat](./cat.png)</div>

Diagrams

See mermaid.js, The magical Markdown I bet you don't know and slaise/High-level-Markdown.

Code blocks for diagrams can either:

• start with ```mermaid and finish with ```, or
• start with :::mermaid and finish with :::.

Flow chart A.K.A. graph

:::mermaid
graph LR
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    subgraph work
    C -->|One| D[Laptop]
    C --x|Two| E[iPhone]
    C -.->|Three| F[fa:fa-car Car]
    C ==> G((Bike))
    C --> J>TV]
    end
:::

graph LR
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    subgraph work
    C -->|One| D[Laptop]
    C --x|Two| E[iPhone]
    C -.->|Three| F[fa:fa-car Car]
    C ==> G((Bike))
    C --> J>TV]
    end

Sequence diagram

:::mermaid
sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!
:::

sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!

Class diagram

:::mermaid
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }
:::

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

State diagram

:::mermaid
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
:::

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

Gantt diagram

:::mermaid
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
:::

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

Pie chart

:::mermaid
pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
:::

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

Math

$\sum_{n=1}^{10} n^2$
$$\sum_{n=1}^{10} n^2$$

\sum_{n=1}^{10} n^2

\sum_{n=1}^{10} n^2

Troubleshooting

Escape the backtick character

Include a non-code formatted backtick by escaping it normally (with a \).

Render it in an inline code block using double backticks instead of single backticks.

Alternatively, use a code block. This will wrap everything in a <pre> HTML tag.
To do this, either indent 4 spaces to start a code block, or use fenced code blocks if supported.

VS Code and mermaid graph in Markdown preview

Install and enable bierner.markdown-mermaid's extension.

Further readings

• Official documentation
• Extended syntax
• Linguist supported language syntax list

Sources

All the references in the [further readings] section, plus the following:

• Escaping backticks
• Escaping backtick in Markdown
• The magical Markdown I bet you don't know
• slaise/High-level-Markdown