myst

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）の値
- セル内に複数行のコンテンツを含める場合はインデントを揃える