Skip to main content

Markdown

Issues​

!!! bug "Nested list"

- [Incorrect rendering of nested lists · Issue #545 · mkdocs/mkdocs](https://github.com/mkdocs/mkdocs/issues/545)

  I'm using prettier to format Markdown and it uses 2 spaces indentation for nested lists, so that i have to install `mdx_truly_sane_lists` extension to bypass this issue

  Well, if I change tab_width to 4 spaces for prettier, there is another issue, see: [Tab width should not affect text alignment after the bullet points in Markdown lists · Issue #5019 · prettier/prettier](https://github.com/prettier/prettier/issues/5019)

!!! bug "Abbreviations"

Prettier will escape asterisk(*) in Markdown, which is used as [a special syntax in Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/abbreviations/).

See also: [Excessive escaping of asterisk](https://github.com/prettier/prettier/issues/3837#issuecomment-687916671)

Playground​

Basic formatting​

===! "Output"

- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
- :smile: :material-github: Search Icons: [Icons + Emojis - Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)
- The `#!python range()` function is used to generate a sequence of numbers.
- Line numbers & highlighting
```py linenums="1" hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
- Code annotation

    ```yaml
    theme:
      features:
        - content.code.annotate #(1)
    ```

    1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted
       text**, images, ... basically anything that can be written in Markdown.

- Nested Lists
  - The first item
    - No. 1
    - No. 2
  - The second item
  - The third item

1. Nested Ordered Lists
  1. The first item
    1. No. 1
    1. No. 2
  1. The second item
  1. The third item

=== "Markdown"

````
- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
- :smile: :material-github: Search Icons: [Icons + Emojis - Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)
- The `#!python range()` function is used to generate a sequence of numbers.
- Line numbers & highlighting
```py linenums="1" hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

- Code annotation

    ```yaml
    theme:
      features:
        - content.code.annotate #(1)
    ```

    1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted
       text**, images, ... basically anything that can be written in Markdown.

- Nested Lists
  - The first item
    - No. 1
    - No. 2
  - The second item
  - The third item

1. Nested Ordered Lists
  1. The first item
    1. No. 1
    1. No. 2
  1. The second item
  1. The third item
````

Admonition​

=== "Output"

!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

???+ note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

??? note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

!!! summary "abstract, summary, tldr"
!!! info "info, todo"
!!! tip "tip, hint, important"
!!! success "success, check, done"
!!! question "question, help, faq"
!!! warning "warning, caution, attention"
!!! failure "failure, fail, missing"
!!! danger "danger, error"
!!! bug "bug"
!!! example "example"
!!! quote "quote, cite"

=== "Markdown"

```
!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

???+ note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

??? note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

!!! summary "abstract, summary, tldr"
!!! info "info, todo"
!!! tip "tip, hint, important"
!!! success "success, check, done"
!!! question "question, help, faq"
!!! warning "warning, caution, attention"
!!! failure "failure, fail, missing"
!!! danger "danger, error"
!!! bug "bug"
!!! example "example"
!!! quote "quote, cite"
```

Table​

===! "Output"

| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

=== "Markdown"

```
| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
```

Keyboard​

===! "Output"

++ctrl+alt+del++

=== "Markdown"

```
++ctrl+alt+del++
```

Embedding external files​

===! "Output"

```yaml title="mkdocs.yml" linenums="1"
--8<-- "mkdocs.yml"
```

=== "Markdown"

````
```yaml title="mkdocs.yml" linenums="1"
--8<--​ "mkdocs.yml"
```
````

Linters​

Vale​

I used textlint along with some rules to lint Markdown files before, but due to performance issue, I now use Vale to achieve the same goal.

Vale runs fast to me, although it has some minor issues on configurations. see:

To bypass these issues, I put configuration file at ~/.vale.ini and style files under ~/.vale-styles, you can find them here: dotfiles/vale at main · masakichi/dotfiles

See also:

Other linters​