markdown-formatting

Markdown & MDX のフォーマットとリンティング

すべての Markdown ルールを包括的に理解したうえで、markdownlint CLI ツールを使って Markdown ファイルと MDX ファイルをフォーマットし、リンティングします。

クイックスタート

# Check if markdownlint is available
which markdownlint || which markdownlint

# Install if needed
pnpm add -D markdownlint
# or
npm install -g markdownlint

# Auto-fix files (markdown and MDX)
markdownlint --fix "**/*.{md,mdx}"

# Check specific files
markdownlint README.md docs/**/*.md content/**/*.mdx

設定の検出

次の順序で設定ファイルを確認します。

1. .markdownlint.json
2. .markdownlint.jsonc
3. .markdownlint.yaml
4. .markdownlintrc
5. package.json の markdownlint キー

一般的なワークフロー

1. 環境を検出：markdownlint CLI を確認します
2. 設定を探す：設定ファイルを探します
3. リンターを実行：問題を特定します
4. 修正を適用：自動修正または手動で修正します
5. 確認：再実行して問題が解消されたことを確認します

よくある問題と簡単な修正方法

見出し

• MD001：見出しレベルを順に上げます（# → ## → ###。# → ### は不可）
• MD018/MD019：ハッシュ記号の後に半角スペースを1つ入れます（# Heading。#Heading は不可）
• MD022：見出しの前後に空行を入れます
• MD025：文書内の H1 は1つだけにします
• MD041：1行目を H1 にします

# Main Title

## Section

### Subsection

Content here...

リスト

• MD004：リストマーカーを統一します（すべて - またはすべて *）
• MD007：ネストしたリストはスペース2つでインデントします
• MD030：リストマーカーの後に半角スペースを1つ入れます
• MD032：リストの前後に空行を入れます

- Item 1
  - Nested item
  - Another nested
- Item 2

空白

• MD009：行末にスペースを入れません
• MD010：タブではなくスペースを使います
• MD012：空行は1行だけにします（複数行にしません）
• MD047：ファイルの末尾に改行を入れます

リンクと画像

• MD034：URL を <> で囲みます：<http://example.com>
• MD042：リンクにはテキストが必要です：[リンクテキスト](url)。[](url) は不可
• MD045：画像には代替テキストが必要です：![説明](image.png)

コードブロック

• MD031：コードブロックの前後に空行を入れます
• MD040：コードブロックの言語を指定します

Text before

```javascript
const code = 'here';
```

Text after

CLI コマンド

# Fix all markdown and MDX files
markdownlint --fix "**/*.{md,mdx}"

# Fix specific files
markdownlint --fix README.md CHANGELOG.md content/blog.mdx

# Check without fixing
markdownlint "**/*.{md,mdx}"

# Use specific config
markdownlint --config .markdownlint.json "**/*.{md,mdx}"

# Ignore specific rules
markdownlint --disable MD013 MD033 "**/*.{md,mdx}"

# Output JSON for parsing
markdownlint --json "**/*.{md,mdx}"

よく使うパターン

複数の問題をまとめて修正する

#Title
Some text with trailing spaces
 Tab indented line

- Item 1
* Item 2
Visit http://example.com


# Title

Some text with trailing spaces
    Space indented line

- Item 1
- Item 2

Visit <http://example.com>

package.json に追加する

{
  "scripts": {
    "lint:md": "markdownlint \"**/*.{md,mdx}\" --ignore node_modules",
    "lint:md:fix": "markdownlint \"**/*.{md,mdx}\" --ignore node_modules --fix"
  }
}

詳細なルールのリファレンス

すべての Markdown ルールについて、例と修正方法を含む詳細なドキュメントは、rules-reference.md を参照してください。

リソース

• markdownlint GitHub
• markdownlint ルール