| name | myst |
| description | MyST記法のルール。(1) パイプテーブルではなくlist-tableディレクティブを使用する。(2) 太字見出し＋箇条書きの複数グループはlist-tableに変換する。(3) コードブロックは外部ファイルからliteralincludeで取り込む。(4) フロー図はmermaidディレクティブで記述する。(5) 注意喚起はAdmonitionディレクティブを使用する。(6) 用語説明は定義リストで記述する。MyST/Sphinxのマークダウンを生成するときに適用する。 |
MyST 記法ルール
テーブル
- パイプテーブル（
| col1 | col2 | 形式）は使用禁止
- テーブルは必ず
:::{list-table} ディレクティブで記述する
- 列数は3列以内とする。4列以上になる場合はスライドを分割する
- セル内の文字数が多くテーブルでは視認性が悪い場合も、スライドの分割を検討する
list-table の書式
:::{list-table}
:header-rows: 1
:widths: auto
* - ヘッダ1
- ヘッダ2
* - データ1
- データ2
:::
必須オプション
:header-rows: を必ず指定する（ヘッダ行がない場合は 0）:widths: auto を基本とする（明示的な幅指定が必要な場合のみ整数列を使用）
利用可能なオプション
:align: — left / center / right:header-rows: — ヘッダ行数（デフォルト: 0）:stub-columns: — スタブ列数（デフォルト: 0）:width: — テーブル全体の幅（長さまたはパーセント）:widths: — 列幅の比率（整数列または auto）:class: — CSSクラス:name: — 参照用ターゲット名
箇条書きグループの表化
太字見出し＋箇条書きのグループが複数並ぶパターンは list-table に変換する。各グループの見出しをヘッダ行、箇条書きをセル内の箇条書きとして配置する。
禁止パターン
**カテゴリA**
- 項目1
- 項目2
**カテゴリB**
- 項目3
- 項目4
正しい記法
:::{list-table}
:header-rows: 1
:widths: auto
* - カテゴリA
- カテゴリB
* - - 項目1
- 項目2
- - 項目3
- 項目4
:::
セル内箇条書きの構文
* - - item は「行開始 → セル開始 → 箇条書き項目」の3段ネスト- 同一セル内の後続項目は
- item（4スペースインデント）
行単位の比較テーブル
列を横断して1対1で対応する比較項目は、セル内箇条書きではなく独立したテーブル行として記述する。
判断基準
- 各列の項目が行単位で対応する比較 → 独立行
- 1つのカテゴリ内の複数の補足説明 → セル内箇条書き
禁止パターン
対応する項目をセル内箇条書きにまとめてはならない:
:::{list-table}
:header-rows: 1
:widths: auto
* - 従来の課題
- SDD
* - - 曖昧さに気づかない
- 乖離が発生
- コードが真実の源泉
- - 考えが明確化
- コードを生成
- コードも更新
:::
正しい記法
各対応を独立した行として記述する:
:::{list-table}
:header-rows: 1
:widths: auto
* - 従来の課題
- SDD
* - 曖昧さに気づかない
- 考えが明確化
* - 乖離が発生
- コードを生成
* - コードが真実の源泉
- コードも更新
:::
コードの取り込み
外部ファイルとして存在するコードはインラインコードブロックではなく literalinclude で取り込む。
基本書式
:::{literalinclude} path/to/file.py
:language: python
:::
パスはドキュメントファイルからの相対パス。/ 始まりはソースディレクトリのルートからの相対パス。
主要オプション
:language: — シンタックスハイライトの言語:lines: — 行範囲の指定（例: 1-5, 1,3,5-10）:start-after: — 指定テキストの後から取り込み開始:end-before: — 指定テキストの前で取り込み終了:emphasize-lines: — 強調表示する行（例: 3,5-7）:linenos: — 行番号を表示:caption: — キャプション:pyobject: — 特定のPythonオブジェクトを抽出:dedent: — インデントを除去する文字数
禁止パターン
ファイルとして存在するコードをインラインで記述してはならない:
```python
def hello():
print("Hello")
```
許容パターン
説明用の5行以下のコード片はインラインコードブロックを許容する:
```bash
# プロジェクト初期化
specify init
```
6行以上のコードや、外部ファイルとして存在するコードは literalinclude を使用すること。
リモートファイルの取り込み（rli）
リモートURL上のファイルは literalinclude ではなく rli（sphinxext-remoteliteralinclude）で取り込む。literalinclude と同じオプションが使用可能。
:::{rli} https://raw.githubusercontent.com/owner/repo/refs/heads/main/path/to/file.md
:language: markdown
:start-after: "セクション見出し"
:end-before: "次のセクション見出し"
:::
- ローカルファイル →
literalinclude
- リモートファイル（GitHub raw URL等）→
rli
正しい記法
:::{literalinclude} examples/hello.py
:language: python
:::
部分的に取り込む場合:
:::{literalinclude} examples/hello.py
:language: python
:start-after: # start example
:end-before: # end example
:::
ダイアグラム
フロー、シーケンス、状態遷移などの図は mermaid ディレクティブで記述する。ASCIIアートやテキストベースのフローチャートは使用禁止。
基本書式
:::{mermaid}
flowchart LR
A[入力] --> B[処理]
B --> C[出力]
:::
推奨ダイアグラムタイプ（sphinx-oceanid 対応）
flowchart / graph — フローチャート（方向指定: LR, TD, TB, RL, BT）sequenceDiagram — シーケンス図stateDiagram-v2 — 状態遷移図classDiagram — クラス図erDiagram — ER図xychart-beta — XYチャート
上記以外のタイプ（pie, gitGraph, mindmap, gantt 等）は sphinx-oceanid（beautiful-mermaid）で非対応。使用するとビルド時に警告が出る。
オプション
:name: — 本文から相互参照する場合に付与する。相互参照が不要なら省略してよい:caption: — 図のキャプション:align: — left / center / right
禁止パターン
罫線文字やASCIIアートによるフローチャート:
┌─────────┐
│ Specify │ ← 何を作るか明確化
└────┬────┘
↓
┌─────────┐
│ Plan │ ← どう実装するか設計
└─────────┘
正しい記法
:::{mermaid}
flowchart TD
A[Specify] -->|何を作るか明確化| B[Plan]
B -->|どう実装するか設計| C[Tasks]
:::
Admonition
重要な情報、注意点、補足情報を強調する場合は Admonition ディレクティブを使用する。プレーンテキストで「注意:」「ヒント:」と書かない。
基本書式
:::{note}
ここに補足情報を記述する
:::
カスタムタイトルを付ける場合:
:::{admonition} セキュリティに関する注意
:class: warning
認証情報をコードに埋め込まないこと
:::
使用可能なタイプ
note — 一般的な補足情報tip — 実践的なアドバイスwarning — 注意喚起important — 重要な詳細seealso — 関連情報への参照
コンテンツは1〜3行程度に簡潔にまとめること。
禁止パターン
プレーンテキストで注意喚起を記述してはならない:
注意: この操作は取り消せません
ヒント: 先にバックアップを取ることを推奨します
正しい記法
:::{warning}
この操作は取り消せない
:::
:::{tip}
先にバックアップを取ることを推奨する
:::
定義リスト
用語や概念の説明を列挙する場合は定義リスト構文を使用する。箇条書きで代用しない。
基本書式
SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法
TDD
: テスト駆動開発。テストを先に書いてから実装する手法
複数の定義を持つ場合:
API
: アプリケーションプログラミングインターフェース
: 外部システムとのデータ交換の規約
禁止パターン
箇条書きで定義リストを代用してはならない:
- **SDD**: 仕様駆動開発。仕様書を起点にコードを生成する手法
- **TDD**: テスト駆動開発。テストを先に書いてから実装する手法
正しい記法
SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法
TDD
: テスト駆動開発。テストを先に書いてから実装する手法
構文の注意点
コロンフェンスの統一
- ディレクティブの囲みにはコロンフェンス（
:::）を使用する
- バッククォートフェンス（
```）でディレクティブを囲まない
# 正しい
:::{note}
内容
:::
# 禁止
```{note}
内容
### list-table の構文
- `* -` は新しい行（row）の開始
- ` -`（インデント付きハイフン）は列（column）の値
- セル内に複数行のコンテンツを含める場合はインデントを揃える
