oam/knowledge base/markdown.md

Markdown

ReadMe's Markdown engine.

Compare Markdown implementations at babelmark.

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

Syntax highlighting

Specify the language right after the code block's opening:

def index
  puts "hello world"
end

private void index(){
  MessageBox.Show("hello world");
}

TODO lists

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

Flowchart 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

Alerts

Uses the Alert extension.

Refer Github's alert formatting.

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

---

Note

Useful information that users should know, even when skimming content.

---

Tip

Helpful advice for doing things better or more easily.

---

Important

Key information users need to know to achieve their goal.

---

Warning

Urgent info that needs immediate user attention to avoid problems.

---

Caution

Advises about risks or negative outcomes of certain actions.

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
• Github's alert formatting
• Live editor

Sources

• Basic syntax
• Code blocks
• Escaping backticks
• Escaping backtick in Markdown
• The magical Markdown I bet you don't know
• slaise/High-level-Markdown
• Syntax highlighting in Markdown