SpecDojo Handbook

日本語

English

日本語

English

Appearance

ドキュメント編集ガイド ​

Document Editing Guide

SpecDojoで扱うドキュメントの編集に役立つ、Visual Studio Code (VS Code) や各種ツールの設定や操作方法について説明します。

1. 見出しに番号を付与 ​

1.1. コマンドで一括付与（いちばん簡単） ​

  1. コマンドパレットを開く

    • Windows/Linux: Ctrl + Shift + P
    • Mac: Cmd + Shift + P

  2. section numbers と入力

  3. Markdown All in One: Add/Update section numbers を実行

これで例えば、

md
## セクション1

### 小見出し

が、

md
## 1. セクション1

### 1.1. 小見出し

1.2. 「#（タイトル）は番号なし、## から番号にしたい」場合 ​

「ドキュメントのタイトル（#）は番号を付けず、## から 1, 1.1…にしたい」ケースが多いです。 その場合は 見出しレベルの対象範囲を設定してから、上の Add/Update section numbers を実行します。

settings.json に例としてこれを追加：

json
"markdown.extension.toc.levels": "2..6"

これで ##〜###### を対象にしやすくなります（タイトル # を“番号の起点”にしない運用）。

1.3. 注意点（地味にハマりどころ） ​

  • この機能は「表示だけで番号を出す」のではなく、見出しテキスト自体を書き換えます（## 1. 見出し のように）。 → 見出しへのリンク（[...](#見出し)）を手で書いていると、番号付与後にズレることがあります。

2. Markdown プレビューの使い方 ​

VS Code では、Markdown ファイルを編集しながら、 リアルタイムで表示結果を確認できます。

ドキュメント作成・レビュー時には、必ずプレビューを併用してください。

2.1. 基本操作 ​

2.1.1. プレビューを開く ​

  • Windows / Linux: Ctrl + Shift + V
  • macOS: Cmd + Shift + V

現在の Markdown ファイルのプレビューが開きます。

2.1.2. 編集画面とプレビューを並べて表示（推奨） ​

  • Windows / Linux: Ctrl + K → V
  • macOS: Cmd + K → V

画面が左右に分割され、

  • 左：Markdown 編集
  • 右：プレビュー

という構成になります。

このモードで編集すると、変更内容が即座にプレビューへ反映されるため、 レイアウト・表・見出し構成を確認しながら作業できます。

2.2. おすすめの使い方 ​

  1. ドキュメントを開く
  2. Ctrl/Cmd + K → V で分割プレビュー
  3. 表や見出しを編集
  4. プレビューで表示を最終確認

2.3. よくあるミス ​

ミス防止策
表のレイアウト崩れに気づかない常に分割プレビューを使う
見出し階層の誤りプレビューの目次表示で確認
空行不足による段落崩れプレビューで段落境界を確認

2.4. なぜプレビューが重要か ​

Markdown は 書いた内容＝表示結果ではありません。 特に以下は、必ずプレビューで確認してください。

  • 表の崩れ
  • 箇条書きのネスト
  • 見出しレベル
  • 改行位置

3. Markdown 表フォーマットガイド ​

本プロジェクトでは、Markdown の表を常に 読みやすく・統一された形式に保つため、 専用の表フォーマット機能を用意しています。

vs code の拡張機能で用意されている表のフォーマッターは多々ありますが、 列幅を合わせるために一行の変更が表全てに及ぶことがあり、Git の差分が大きくなりがちです。 本機能は、表内の不要な差分を最小化することに特化しています。

  • 列数が少ない表(5列以下が目安)については、vs code 標準の表フォーマッターを使ってください。
  • 列数が多い表については、本機能を使ってください。なお、本プロジェクトではPrettierを使っていますので、競合を避けるために、表の直前に<!-- prettier-ignore --> のコメントを挿入するしてください。

このガイドでは、本機能の使い方と設計思想を説明します。

※コードはtools/docs/src/fmt-md-table.tsにあります。

3.1. この機能で何が起きるか ​

表をフォーマットすると、以下のルールが適用されます。

  • 左寄せ

  • 各セルの左右に必ず1スペース

  • 区切り行は必ず次の形式に統一

    text
    | --- | --- | --- |

  • 列幅の自動調整は行わない

    • （Git の差分が不要に大きくならないため）

  • セルの内容は一切変更されない

    • _ や * などの文字もそのまま保持されます

3.1.1. 例 ​

フォーマット前：

text
|a|bbb|c|
|-|--|----|
|1|  2|3|

フォーマット後：

text
| a | bbb | c |
| --- | --- | --- |
| 1 | 2 | 3 |

3.2. 使い方 ​

3.2.1. Step 1：カーソルを表の中に置く ​

Markdown ファイルを開き、 フォーマットしたい表の中にカーソルを置きます。

このとき、カーソルが置かれている表だけが整形されます。 ファイル内の他の表は一切変更されません。

3.2.2. Step 2：コマンドを実行 ​

コマンドパレットを開きます。

  • Windows / Linux: Ctrl + Shift + P
  • macOS: Cmd + Shift + P

次のコマンドを実行してください。

text
Tasks: Run Task

次に、一覧から次のタスクを選択します。

text
Format Markdown Table

即座に表が整形されます。

3.3. この仕組みを使う理由 ​

この方式により、次のメリットがあります。

  • ドキュメントの 可読性が向上
  • 表の形式が チーム全体で統一
  • Git の差分が最小化
  • フォーマッタによる意図しない変換（\_ など）を防止

3.4. 🛠（任意）ショートカットの設定 ​

よく使う場合は、各自でショートカットを設定できます。

  1. Keyboard Shortcuts を開く

  2. 次のコマンドを検索

    text
    workbench.action.tasks.runTask

  3. 対象タスク

    text
    Format Markdown Table

  4. 好きなキーを割り当てる

3.5. 注意事項 ​

  • 標準的な GitHub Flavored Markdown の表に対応しています
  • Prettierに競合しますので、この機能を使う場合は、表の直前に<!-- prettier-ignore --> のコメントを挿入することで、Prettier の整形を無効化してください
  • 表以外の文章には影響しません