MyST 記法ルール

テーブル

•パイプテーブル（| col1 | col2 | 形式）は使用禁止
•テーブルは必ず :::{list-table} ディレクティブで記述する
•列数は3列以内とする。4列以上になる場合はスライドを分割する
•セル内の文字数が多くテーブルでは視認性が悪い場合も、スライドの分割を検討する

list-table の書式

code

:::{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 に変換する。各グループの見出しをヘッダ行、箇条書きをセル内の箇条書きとして配置する。

禁止パターン

code

**カテゴリA**

- 項目1
- 項目2

**カテゴリB**

- 項目3
- 項目4

正しい記法

code

:::{list-table}
:header-rows: 1
:widths: auto

* - カテゴリA
  - カテゴリB
* - - 項目1
    - 項目2
  - - 項目3
    - 項目4
:::

セル内箇条書きの構文

•* - - item は「行開始 → セル開始 → 箇条書き項目」の3段ネスト
•同一セル内の後続項目は - item（4スペースインデント）

行単位の比較テーブル

列を横断して1対1で対応する比較項目は、セル内箇条書きではなく独立したテーブル行として記述する。

判断基準

•各列の項目が行単位で対応する比較 → 独立行
•1つのカテゴリ内の複数の補足説明 → セル内箇条書き

禁止パターン

対応する項目をセル内箇条書きにまとめてはならない:

code

:::{list-table}
:header-rows: 1
:widths: auto

* - 従来の課題
  - SDD
* - - 曖昧さに気づかない
    - 乖離が発生
    - コードが真実の源泉
  - - 考えが明確化
    - コードを生成
    - コードも更新
:::

正しい記法

各対応を独立した行として記述する:

code

:::{list-table}
:header-rows: 1
:widths: auto

* - 従来の課題
  - SDD
* - 曖昧さに気づかない
  - 考えが明確化
* - 乖離が発生
  - コードを生成
* - コードが真実の源泉
  - コードも更新
:::

コードの取り込み

外部ファイルとして存在するコードはインラインコードブロックではなく literalinclude で取り込む。

基本書式

code

:::{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: — インデントを除去する文字数

禁止パターン

ファイルとして存在するコードをインラインで記述してはならない:

code

```python
def hello():
    print("Hello")
```

許容パターン

説明用の5行以下のコード片はインラインコードブロックを許容する:

code

```bash
# プロジェクト初期化
specify init
```

6行以上のコードや、外部ファイルとして存在するコードは literalinclude を使用すること。

リモートファイルの取り込み（rli）

リモートURL上のファイルは literalinclude ではなく rli（sphinxext-remoteliteralinclude）で取り込む。literalinclude と同じオプションが使用可能。

code

:::{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

正しい記法

code

:::{literalinclude} examples/hello.py
:language: python
:::

部分的に取り込む場合:

code

:::{literalinclude} examples/hello.py
:language: python
:start-after: # start example
:end-before: # end example
:::

ダイアグラム

フロー、シーケンス、状態遷移などの図は mermaid ディレクティブで記述する。ASCIIアートやテキストベースのフローチャートは使用禁止。

基本書式

code

:::{mermaid}
flowchart LR
  A[入力] --> B[処理]
  B --> C[出力]
:::

推奨ダイアグラムタイプ

•flowchart — フローチャート（方向指定: LR, TD, TB, RL, BT）
•sequenceDiagram — シーケンス図
•stateDiagram-v2 — 状態遷移図
•gantt — ガントチャート
•classDiagram — クラス図

上記以外のタイプ（pie, gitGraph, mindmap 等）も使用可能。

オプション

•:name: — 本文から相互参照する場合に付与する。相互参照が不要なら省略してよい
•:caption: — 図のキャプション
•:align: — left / center / right

禁止パターン

罫線文字やASCIIアートによるフローチャート:

code

┌─────────┐
│ Specify │ ← 何を作るか明確化
└────┬────┘
     ↓
┌─────────┐
│  Plan   │ ← どう実装するか設計
└─────────┘

正しい記法

code

:::{mermaid}
flowchart TD
  A[Specify] -->|何を作るか明確化| B[Plan]
  B -->|どう実装するか設計| C[Tasks]
:::

Admonition

重要な情報、注意点、補足情報を強調する場合は Admonition ディレクティブを使用する。プレーンテキストで「注意:」「ヒント:」と書かない。

基本書式

code

:::{note}
ここに補足情報を記述する
:::

カスタムタイトルを付ける場合:

code

:::{admonition} セキュリティに関する注意
:class: warning

認証情報をコードに埋め込まないこと
:::

使用可能なタイプ

•note — 一般的な補足情報
•tip — 実践的なアドバイス
•warning — 注意喚起
•important — 重要な詳細
•seealso — 関連情報への参照

コンテンツは1〜3行程度に簡潔にまとめること。

禁止パターン

プレーンテキストで注意喚起を記述してはならない:

code

注意: この操作は取り消せません

ヒント: 先にバックアップを取ることを推奨します

正しい記法

code

:::{warning}
この操作は取り消せない
:::

:::{tip}
先にバックアップを取ることを推奨する
:::

定義リスト

用語や概念の説明を列挙する場合は定義リスト構文を使用する。箇条書きで代用しない。

基本書式

code

SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法

TDD
: テスト駆動開発。テストを先に書いてから実装する手法

複数の定義を持つ場合:

code

API
: アプリケーションプログラミングインターフェース
: 外部システムとのデータ交換の規約

禁止パターン

箇条書きで定義リストを代用してはならない:

code

- **SDD**: 仕様駆動開発。仕様書を起点にコードを生成する手法
- **TDD**: テスト駆動開発。テストを先に書いてから実装する手法

正しい記法

code

SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法

TDD
: テスト駆動開発。テストを先に書いてから実装する手法

構文の注意点

コロンフェンスの統一

•ディレクティブの囲みにはコロンフェンス（:::）を使用する
•バッククォートフェンス（```）でディレクティブを囲まない

code

# 正しい
:::{note}
内容
:::

# 禁止
```{note}
内容

code


### list-table の構文

- `* -` は新しい行（row）の開始
- `  -`（インデント付きハイフン）は列（column）の値
- セル内に複数行のコンテンツを含める場合はインデントを揃える