6.5 KiB
Markdown
ReadMe's Markdown engine.
Compare Markdown implementations at babelmark.
TL;DR
Diagrams
Use mermaid.js to include diagrams and graphs.
See also The magical Markdown I bet you don't know and slaise/High-level-Markdown.
Folded content
Use a <details> HTML tag:
<details>
<summary>Fold/Open</summary>
Folded content
</details>
Math
Inline expressions: surround the expression with $.
$\sum_{n=1}^{10} n^2$
\sum_{n=1}^{10} n^2
Block expressions: surround the expression with $$.
$$\sum_{n=1}^{10} n^2$$
\sum_{n=1}^{10} n^2
Syntax highlighting in code blocks
Specify the language right after the code block's opening:
def index
puts "hello world"
end
private void index(){
MessageBox.Show("hello world");
}
Refer Syntax highlighting in markdown and linguist supported language syntax list for recognized languages and their aliases.
To do 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
- 2
- a
- Point 3
Alerts
Alerts are not defined in the base Markdown specification.
They are extensions that the most famous flavours introduced or adopted, each with small but annoying differences.
GitHub formatting
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.
GitLab formatting
Refer GitLab Flavored Markdown.
> [!note]
> Information that users should take into account, even when skimming.
> [!tip]
> Optional information to help a user be more successful.
> [!important]
> Crucial information necessary for users to succeed.
> [!caution]
> Negative potential consequences of an action.
> [!warning]
> Critical potential risks.
Note
Information that users should take into account, even when skimming.
Tip
Optional information to help a user be more successful.
Important
Crucial information necessary for users to succeed.
Caution
Negative potential consequences of an action.
Warning
Critical potential risks.
Images
Add an image:
![description][reference name]
Control width and height:
<img src="./cat.png" width=300px height=200px />
Align in the center:
<div align="center"></div>
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.
Render mermaid.js graphs in VS Code's 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
- Mermaid.js
- MyST extension for technical, scientific communication and publication