Skip to content

lib9-markdown-style-guide.md

Latest commit

 

History

History
203 lines (139 loc) · 4.08 KB

lib9-markdown-style-guide.md

File metadata and controls

203 lines (139 loc) · 4.08 KB
Raw

Lib9 Markdown Style Guide

Use basic Markdown

Use basic Markdown that is compatible with both CommonMark and Djot. You can also use tables and footnotes which are widely supported. You should stick to the following syntax:

  • Headings #, ##, ###

    Add a blank line before and after a heading.

  • _emphasis_

  • **strong emphasis**

  • `inline code`

  • > Blockquote

  • [link](https://example.com), <https://example.com>, and [labelled link][label]

    A [labelled link][label].

[label]: https://example.com

  • [^footnote]

    Here's the reference[^foo].

[^foo]: This is a footnote.

  • Images ![alt text](img.jpg) and ![alt text][label]

    ![alt text][label].

[label]: img.jpg

  • Lists, enumerations, and task lists

    Note that in Djot, a list must be preceded by a blank line. This also applies to sub-lists.

    -   item 1
-   item 2
    1.  item 1
2.  item 2
    -   [x] task 1 (done)
-   [ ] task 2 (todo)
-   [~] task 3 (removed)

  • Code block

    Specify a language tag.

    ```js
double(5) === 10
```

  • Tables

    The presence of : in the separator determines the column alignment. If no colon is present, then the column uses the default alignment.

    | Item    | Price | # In stock |
| :------ | :---: | ---------: |
| Apples  | 1.99  |        739 |
| Bananas | 1.89  |          6 |

Formatting

  • Write one sentence a line

    This makes git-diff easier.

  • No hard wrap

    Try to write short sentences. Break large sentences at natural places, such as after commas. See Semantic Linefeeds.

  • No trailing spaces

    Some Markdown flavors can interpret them as a hard break. If you want a line break, then insert a blank line.

  • At most three levels of headings

    Two levels are usually sufficient.

  • Use inline links over labelled links

    - A [labelled link][label]
+ An [inline link](https://example.com)

- [label]: https://example.com

    Only use labelled links for repeated links.

    - A [link](https://example.com).
- Again the same [link]((https://example.com))
- Always the same [link](https://example.com)
+ A [link][label]
+ Again the same [link][label]
+ Always the same [link][label]

+ [label]: https://example.com

  • Compact and wide lists, enumerations, and task lists

    If a list item consists of several lines, then add a blank line between every list item.

    - Item 1

  Second paragraph of the first item

- Item 2

- Item 3

    Otherwise, use the compact form.

    - Item 1
- Item 2
- Item 3

    This also applies to enumerations and task lists.

  • Use ASCII diagrams

    A markdown file should be readable in its original form. A simple ASCII art diagram can often replace an image.

    Some editors such as ASCII flow can help to create diagrams. You can even use standardized ASCII art like Svgbob:

    ```svgbob
┌──────┐     ┌──────┐
│step 1├────►│step 2│
└──────┘     └──────┘
```

    You can generate ASCII diagrams from other textual formats.

  • Use Mermaid diagrams

    A lot of services, such as GitHub and GitLab, render Mermaid diagrams.

    ```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

  • Use LaTeX math

    ```math
a^2 + b^2 = c^2
```

  • Use diff blocks

    ```diff
  unchanged
- removed
+ added
```