Markdown執筆ルール

• 作成:2026/02/21
• 更新:2026/02/21
• 著者:
  Takeshi Takatsudo

このドキュメントは、Markdownで記事を執筆する際の構造的なルールをまとめたものです。文体や言葉遣いについては 執筆スタイル を参照してください。

見出しと強調のルール

太字をセクション見出しとして使わない

太字（**text**）やイタリック（*text*）は、文中のインライン強調にのみ使用する。セクションタイトルには必ず見出し（##、###、####）を使う。

<!-- ❌ Bad: 太字を見出しとして使用 -->

**セクションタイトル:**

- リスト項目
- リスト項目

<!-- ✅ Good: 適切な見出しを使用 -->

### セクションタイトル

- リスト項目
- リスト項目

太字をリスト項目のヘッダーとして使わない

リスト項目の先頭で太字をヘッダー代わりに使わない。

<!-- ❌ Bad: 太字をリストヘッダーとして使用 -->

- **新規フィッティング実行**
  - ユーザーが新しいフィッティングを実行したとき
  - バッジの非表示状態がリセットされる
- **localStorageクリア**
  - ブラウザキャッシュのクリア
  - プライベートブラウジングモード

<!-- ✅ Good: プレーンテキストでリスト項目を記述 -->

- 新規フィッティング実行
  - ユーザーが新しいフィッティングを実行したとき
  - バッジの非表示状態がリセットされる
- localStorageクリア
  - ブラウザキャッシュのクリア
  - プライベートブラウジングモード

<!-- ✅ Good: インライン強調として太字を使用 -->

- ユーザーが**新規フィッティング**を実行すると、バッジの非表示状態がリセットされる
- ブラウザキャッシュのクリアや**プライベートブラウジングモード**ではlocalStorageがクリアされる

日本語文中での太字の使用に注意

日本語文中で太字（**text**）を使用する際、太字の前後が日本語文字に直接隣接していると、MDXパーサーが正しく認識できずに**がそのまま表示されてしまうことがある。

<!-- ❌ Bad: 太字が日本語文字に直接隣接 -->

それが**構文解析**して**AST**という形式に変換し

<!-- ✅ Good: 鉤括弧を使用（技術用語の導入に適切） -->

それが「構文解析」して「AST」という形式に変換し

<!-- ✅ Good: 文の区切りで太字を使用 -->

これを**構文解析**と呼びます。**AST**という形式に変換します。

<!-- ✅ Good: 太字の前後に句読点や括弧がある -->

方法があります。それが**構文解析（パース）**です。

対処法：

• 技術用語の導入には鉤括弧「」を使用する（日本語として自然）
• 太字を使う場合は、文の先頭や末尾、または句読点の直後に配置する
• 太字の後ろに助詞（が、を、に、は等）が続く場合は特に注意

深いネストの見出しは基本的に避ける

記事は文字数に制限があり、ブログのようなスタイルで、超長編のストーリーは含まない。長くなる場合は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（リンク形式）

Docusaurusブロック記法

Docusaurusには様々なブロック記法（アドモニション）があるが、記事執筆では以下の2種類のみを使用する。

注記（note）

本文の補足説明や注意事項を示す場合に使用する。

:::note[注記]

The quick brown fox jumps over the lazy dog.

:::

注記

The quick brown fox jumps over the lazy dog.

備考（info）

本筋から外れるが関連する追加情報を示す場合に使用する。「ちなみに」「余談ですが」のようなニュアンス。

:::info[備考]

The quick brown fox jumps over the lazy dog.

:::

備考

The quick brown fox jumps over the lazy dog.

使用しないブロック記法

以下のブロック記法は記事執筆では使用しない：

• :::tip - ヒント
• :::warning - 警告
• :::danger - 危険
• :::caution - 注意

これらはドキュメントサイトでは有用だが、記事としては「注記」と「備考」の2種類で十分であり、種類を絞ることで一貫性を保つ。

esaへの変換マッピング

esaに記事を投稿する際、DocusaurusのアドモニションをesaのMarkdown Alert形式に変換する必要がある。

Docusaurus	esa
:::note	> [!NOTE]
:::info	> [!NOTE]

変換例:

Docusaurus形式:

:::note[注記]

補足説明の内容です。
複数行も可能です。

:::

esa形式:

> [!NOTE]
> 補足説明の内容です。
> 複数行も可能です。

esaのMarkdown Alert形式では、各行の先頭に> が必要。

この変換は/convert-to-esaコマンドで自動的に行われる。

なぜこれらのルールが重要か

これらの構造的ルールは、単なるスタイルの好みではなく、セマンティックHTMLとアクセシビリティに基づいている。

• 太字・イタリックはインライン強調用: HTMLでは <strong> と <em> タグに変換される。これらは文中の強調用であり、見出しとして使うとセマンティック構造が壊れる
• 適切な見出しはドキュメント階層を作る: 見出し（##、###、####）は目次生成やスクリーンリーダーのナビゲーションに使用される。太字を見出し代わりに使うと、これらの機能が正しく動作しない
• リストタイプの混在は視覚的階層を乱す: 番号付きリストと箇条書きリストを混在させると、読者にとって情報の優先度や関係性が不明確になる
• アクセシビリティへの配慮: スクリーンリーダーは見出しやリストの構造に依存してドキュメントをナビゲートする。正しい構造は視覚障害を持つ読者にとって特に重要