md-syntax

Markdown 作成ガイドライン

Markdown ファイルを作成または編集する際は、以下のルールに従ってください。

ルール

• コードブロックには必ず言語を指定する - bash、yaml、json、text、hcl、go などを使用します。言語指定のない ``` は使用しないでください
• AI が生成したような不要な表現は避ける - 絵文字、グリフ、エムダッシュは使用しないでください
• セクションタイトルには太字ではなく見出しを使う - ##、### などの適切な見出しレベルを使い、独立した行に **太字** を置かないでください
• ファイルごとに H1 は 1 つだけ - 冒頭に # タイトル を 1 つだけ置きます
• 最初の行は H1 にする - ファイルは # タイトル で始めます
• フォーマッターの仕様に従って記述する - 書き込みのたびに PostToolUse フックが Markdown を再フォーマットします。書き換えられる内容と、自動修正できない lint ルールについては /md-lint を参照してください
• スタイルの間には空行を入れる - Markdown の種類が変わる箇所には、空行を 1 行入れます

例

スタイルの間に空行を入れる

Markdown の種類が変わる箇所には、空行を 1 行入れてください。Markdown のスタイル間に複数の空行を入れないでください。

正しい例

## Heading

paragraph

- list item one
- list item two

> block quote

誤った例

## Heading


paragraph
- list item one
- list item two
> block quote

太字ではなく見出しを使う

正しい例

### Heading

paragraph

誤った例

**heading incorrect bold**

paragraph

コードブロック

言語を必ず指定してください。

言語を指定した正しい例

```bash
#!/bin/bash
```

言語を指定していない誤った例

```
#!/bin/bash
```

末尾の改行

ファイルの末尾は、最後の内容の後に改行を 1 つだけ入れてください。フェンスは最後のバイトを隠すため、フェンスで囲まれた例ではこれを示せません。tail -c 1 file.md | xxd で確認してください。出力は 0a でなければなりません。