Markdown執筆ルール
Markdownで記事を執筆する際の構造的なルールをまとめたドキュメント。文体ではなく、Markdownの書き方に関するルール。
このドキュメントは、Markdownで記事を執筆する際の構造的なルールをまとめたものです。文体や言葉遣いについては 執筆スタイル を参照してください。
見出しと強調のルール
太字をセクション見出しとして使わない
太字（**text**）やイタリック（*text*）は、文中のインライン強調にのみ使用する。セクションタイトルには必ず見出し（##、###、####）を使う。
<!-- ❌ Bad: 太字を見出しとして使用 -->
**セクションタイトル:**
- リスト項目
- リスト項目
<!-- ✅ Good: 適切な見出しを使用 -->
### セクションタイトル
- リスト項目
- リスト項目太字をリスト項目のヘッダーとして使わない
リスト項目の先頭で太字をヘッダー代わりに使わない。
<!-- ❌ Bad: 太字をリストヘッダーとして使用 -->
- **新規フィッティング実行**
- ユーザーが新しいフィッティングを実行したとき
- バッジの非表示状態がリセットされる
- **localStorageクリア**
- ブラウザキャッシュのクリア
- プライベートブラウジングモード
<!-- ✅ Good: プレーンテキストでリスト項目を記述 -->
- 新規フィッティング実行
- ユーザーが新しいフィッティングを実行したとき
- バッジの非表示状態がリセットされる
- localStorageクリア
- ブラウザキャッシュのクリア
- プライベートブラウジングモード
<!-- ✅ Good: インライン強調として太字を使用 -->
- ユーザーが**新規フィッティング**を実行すると、バッジの非表示状態がリセットされる
- ブラウザキャッシュのクリアや**プライベートブラウジングモード**ではlocalStorageがクリアされる日本語文中での太字の使用
本プロジェクトでは remark-cjk-friendly プラグインを導入済みのため、日本語文中で太字（**text**）を使用しても正しくレンダリングされる。CJK句読点が ** に隣接していても問題ない。
ただし、他のMarkdownレンダラー（GitHubなど）ではCommonMark仕様の制約により、CJK句読点が ** の内側に隣接している場合に太字が認識されないことがある。GitHub上でのREADME表示なども考慮する場合は、太字の内側に句読点を含めないようにすると安全。
深いネストの見出しは基本的に避ける
記事は文字数に制限があり、ブログのようなスタイルで、超長編のストーリーは含まない。長くなる場合は2〜3本の記事に分割すべきである。そのため、深くネストした見出し構造は基本的に避ける。
基本ルール：
- 基本的にh2を使う
ただし、h3、h4、h5の使用を禁止するわけではない。
たとえば、以下のような見出し構造の記事があったとする。
## 大きなセクション
### サブセクション1
内容...
### サブセクション2
内容...
### サブセクション3
内容...
### サブセクション4
内容...このh2セクションは長すぎる印象がある。このような場合、見出しレベルを調整することを検討する。
## 大きなセクション
内容...
## サブセクション1
内容...
## サブセクション2
内容...
## サブセクション3
内容...
## サブセクション4
内容...文章が不自然でなければ、多くの場合このほうが読みやすい。
リストのルール
番号付きリストと箇条書きリストを混在させない
同じコンテンツ構造内で、番号付きリスト（ol）と箇条書きリスト（ul）を混在させない。
<!-- ❌ Bad: リストタイプの混在 -->
1. **項目1**: 説明
- サブ項目1-1
- サブ項目1-2
2. **項目2**: 説明
- サブ項目2-1
<!-- ✅ Good: 一貫した箇条書きリスト -->
- 項目1: 説明
- サブ項目1-1
- サブ項目1-2
- 項目2: 説明
- サブ項目2-1リスト内にコードブロックを入れない
リスト項目の中にコードブロックを配置しない。コードブロックはリストの外に、適切なコンテキストとともに配置する。
<!-- ❌ Bad: リスト内のコードブロック -->
- LayoutDivide: 2カラムレイアウトコンポーネント
```jsx
<LayoutDivide>
<LayoutDivideItem>左カラム</LayoutDivideItem>
<LayoutDivideItem>右カラム</LayoutDivideItem>
</LayoutDivide>
```- LayoutDivide: 2カラムレイアウトコンポーネント
<LayoutDivide>
<LayoutDivideItem>左カラム</LayoutDivideItem>
<LayoutDivideItem>右カラム</LayoutDivideItem>
</LayoutDivide>- Column: コンテンツ用の単一カラムラッパー
番号付きリスト vs 見出し
コンテンツの複雑さに応じて、番号付きリストと見出しを使い分ける。
シンプルな内容 → 番号付きリスト
#### メリット
1. メンテナンス性の向上 - スタイルの差別化が容易
2. 効率的なレビュー - シンプルなバリデーション
3. 素早い問題解決 - 明確な防御策複雑な内容（コードブロック、複数段落を含む） → 見出し構造
## 使用方法
### 1. HTMLマークアップ
```html
<div id="app"></div>
```
### 2. 初期化
```js
myLibrary.init({
/* ... */
});
```内容のない連続見出しを避ける
見出しの間には必ず内容を入れる。内容がない場合は番号付きリストを使う。
<!-- ❌ Bad: 内容のない連続見出し -->
### 1. 条件を追加
### 2. 型をインポート
### 3. 設定を返す
<!-- ✅ Good: シンプルなリストに変換 -->
1. 条件を追加
2. 型をインポート
3. 設定を返す水平線（hr）の使用ルール
水平線（---）は、コンテンツの大きな区切りにのみ使用する。
❌ 使用しない場面
- セクション（h2）の区切りとして使用しない
- h2やh3の見出しがある場合、それ自体がセクションの区切りを示すため、水平線は不要
<!-- ❌ Bad: h2の前に水平線は不要 -->
---
## セクション1
内容...
---
## セクション2
内容...<!-- ✅ Good: h2だけでセクションは区切られる -->
## セクション1
内容...
## セクション2
内容...✅ 使用する場面
- 記事内で大きく話題が変わる場合（章をまたぐような区切り）
- 付録や補足情報を本文と明確に分離する場合
- 連載記事の「次回予告」などを本文と分ける場合
## 本文の最後のセクション
本文の内容...
---
## 次回予告
次回は〜について解説します。日本語テキスト内のURL記述
日本語文中にURLを含める際、GitHubが誤ってオートリンクしてしまうインラインURLは避ける。
パターン1: URLを箇条書きで分離
URLが補足情報の場合：
<!-- ✅ Good: 箇条書きで分離 -->
サイト名において、問題が発生していました。
- サイト名
- https://example.com/path/to/pageパターン2: Markdownリンク形式
URLが文の流れに組み込まれる場合：
<!-- ✅ Good: Markdownリンク形式 -->
[サイト名](https://example.com/path/to/page)において、問題が発生していました。避けるべきパターン
<!-- ❌ Bad: 括弧内の生URL（GitHubが誤ってオートリンクする） -->
サイト名（https://example.com/path/to/page）において、問題が発生していました。使い分けの基準：
- URLが参照・補足情報の場合 → パターン1（箇条書き）
- サイト名とURLが自然なクリック可能なユニットを形成する場合 → パターン2（リンク形式）
ブロック記法（アドモニション）
ドキュメントサイトには様々なブロック記法（アドモニション）があるが、記事執筆では以下の2種類のみを使用する。
注記（note）
本文の補足説明や注意事項を示す場合に使用する。
:::note 注記
The quick brown fox jumps over the lazy dog.
::::::note 注記
The quick brown fox jumps over the lazy dog.
:::
備考（info）
本筋から外れるが関連する追加情報を示す場合に使用する。「ちなみに」「余談ですが」のようなニュアンス。
:::info 備考
The quick brown fox jumps over the lazy dog.
::::::info 備考
The quick brown fox jumps over the lazy dog.
:::
使用しないブロック記法
以下のブロック記法は記事執筆では使用しない：
:::tip- ヒント:::warning- 警告:::danger- 危険:::caution- 注意
これらはドキュメントサイトでは有用だが、記事としては「注記」と「備考」の2種類で十分であり、種類を絞ることで一貫性を保つ。
ブログMDXへの変換マッピング
/l-convert-to-articleで下書きをブログ用MDXに変換する際、アドモニション記法をブログのカスタムコンポーネントに変換する。
| ドキュメント記法 | ブログMDX |
|---|---|
:::note 注記 | <Note> |
:::info 備考 | <Info> |
変換例:
ドキュメント形式:
:::note 注記
補足説明の内容です。
複数行も可能です。
:::ブログMDX形式:
<Note>
補足説明の内容です。
複数行も可能です。
</Note>カスタムタイトルがある場合はtitlepropで渡す:
<Note title="カスタムタイトル">
内容
</Note>フロントマターのルール
descriptionの長さ
記事のフロントマターに書くdescriptionは、80文字前後（±20文字、つまり60〜100文字程度）が適切なバランス。短すぎると記事の内容が伝わらず、長すぎるとOGPやカード表示で途切れる。
# ❌ Bad: 短すぎる（39文字）
description: "Claude CodeのAgent Teams機能をいつ使うべきかについて紹介。"
# ✅ Good: 80文字前後（71文字）
description: "Claude CodeのAgent Teams機能をいつ使うべきかという問いに対して、普段の開発で使っている2つのパターンと、git worktreeベースの並列開発の実例を交えて紹介。"なぜこれらのルールが重要か
これらの構造的ルールは、単なるスタイルの好みではなく、セマンティックHTMLとアクセシビリティに基づいている。
- 太字・イタリックはインライン強調用: HTMLでは
<strong>と<em>タグに変換される。これらは文中の強調用であり、見出しとして使うとセマンティック構造が壊れる - 適切な見出しはドキュメント階層を作る: 見出し（
##、###、####）は目次生成やスクリーンリーダーのナビゲーションに使用される。太字を見出し代わりに使うと、これらの機能が正しく動作しない - リストタイプの混在は視覚的階層を乱す: 番号付きリストと箇条書きリストを混在させると、読者にとって情報の優先度や関係性が不明確になる
- アクセシビリティへの配慮: スクリーンリーダーは見出しやリストの構造に依存してドキュメントをナビゲートする。正しい構造は視覚障害を持つ読者にとって特に重要