7.7 KiB
Markdown
ReadMe's Markdown engine.
Compare Markdown implementations at babelmark.
TL;DR
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
Tables
| column 1 | column 2 | column 3 |
| -------- | -------- | -------- |
| a | b | c |
| column 1 | column 2 | column 3 |
|---|---|---|
| a | b | c |
HTML tags can be used within cells to have some control over the content.
| column 1 | column 2 | column 3 |
| -------- | -------- | ----------------------------- |
| a | b<br/>b | <ul><li>c</li><li>c</li></ul> |
| column 1 | column 2 | column 3 |
|---|---|---|
| a | b b |
|
Text in columns can be aligned by putting : in the header delimiter line where the alignment should be.
:--- = left, ---: = right, :---: = center.
| column 4 | column 5 | column 6 |
| :------- | :------: | -------: |
| a | b | c |
| column 4 | column 5 | column 6 |
|---|---|---|
| a | b | c |
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
Simply add an image:
![description][reference name]
More advanced control requires using HTML tags directly:
-
Control width and height:
<img src="cat.png" width=300px height=200px alt="description"/> -
Center the image:
<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