---
name: write-markdown
description: Better markdown writing. Use when writing markdown file.
---

# Markdown writing skill

## Header

-   Insert one empty line after header.

## List

-   Surround lists by one empty line.
-   Use hyphen('-'), DO TNO USE asterrisk('*') or plus('+').
-   Indent of unordered lists use 4 spaces.
-   If the content of every item of the list is fits in a single paragraph, use 1 space after marker. Otherwise, for every item of the list, use 3 spaces for unordered lists, use 2 spaces for ordered lists.

If multiple lines in list, use following syntax:

Bad:

```markdown
-   item that
    is wrapped
-   item 2
    -   item 21
    -   item 22
    -   item 23
-   item 3
```

Good:

```markdown
-   item that
    is wrapped

-   item 2

    -   item 21
    -   item 22
    -   item 23

-   item 3
```

For code block, surround code block by one empty lines:

```markdown
-   item 1

    ```python
    print("hoge 1")
    ```

-   item 2
    -   item 2-1

        ```python
        print("hoge 2-1")
        ```

-   item 3
```

## Table

-   Surround table by one empty lines.

## (Fenced) Code Block

-   Always specify the language of the code is applicable. if code is plain text, use `text` as language.

Bad:

```markdown
    ```
    docs/<bundle>/
    ├── .bundle/            # Reserved. System & AI administrative directory.
    │   ├── CATEGORIES.md
    ...
    ```
```

Good:

```markdown
    ```txt
    docs/<bundle>/
    ├── .bundle/            # Reserved. System & AI administrative directory.
    │   ├── CATEGORIES.md
    ...
    ```
```
