| name | revealjs-authoring |
| description | sphinx-revealjs のスライドを MyST で書くための記法ルール(見出しレベルによるスライド分割、list-table、2 カラムレイアウト等)。extensions に sphinx_revealjs があるプロジェクトで docs/ 配下の .md を編集・作成するときに使用する。汎用 MyST 記法は myst-authoring が担当。 |
| license | MIT |
| allowed-tools | Read, Grep, Glob |
発火条件
docs/conf.py の extensions に sphinx_revealjs を含むプロジェクトで、docs/ 配下の .md を編集・作成する場合- 「スライドを書いて」「このスライドを直して」「スライドに1枚追加して」
myst-authoring との棲み分け
- 汎用 MyST 記法 (ディレクティブ・ロール・相互参照・数式等) →
myst-authoring
- スライドという媒体に固有の制約 (表示領域・スライド分割・レイアウト) → 本スキル
- 両者は同時発火しうる。ルールが矛盾する場合は本スキルのスライド固有ルールを優先する
スライド構造 — 見出しレベル
見出しレベルがスライド分割を決める:
# — タイトルスライド (文書内で1回のみ)## — セクション区切りスライド (横方向のスライド)### — 個別スライド (セクション内の縦方向のスライド)
1スライド1トピック。1つの ### に複数トピックを詰め込まず、スライドを分割する。
禁止パターン
### 機能紹介と導入方法と注意点
- 機能A の説明
- 機能B の説明
- インストール手順
- 設定方法
- 利用時の注意点
正しい記法
### 主な機能
- 機能A の説明
- 機能B の説明
### 導入方法
- インストール手順
- 設定方法
### 利用時の注意点
テーブル
- パイプテーブル (
| col1 | col2 | 形式) は使用禁止。必ず {list-table} ディレクティブで記述する
:header-rows: を必ず指定する (ヘッダ行がない場合は 0):widths: auto を基本とする- 列数は3列以内。4列以上になる場合はスライドを分割する
- セル内の文字数が多くテーブルでは視認性が悪い場合もスライドの分割を検討する
禁止パターン
| ツール | 特徴 |
|---|---|
| Spec Kit | テンプレートとプロンプト |
正しい記法
:::{list-table}
:header-rows: 1
:widths: auto
* - ツール
- 特徴
* - Spec Kit
- テンプレートとプロンプト
:::
行単位の比較テーブル
列を横断して1対1で対応する比較項目は、セル内箇条書きではなく独立したテーブル行として記述する。
禁止パターン
:::{list-table}
:header-rows: 1
:widths: auto
* - 従来の課題
- SDD
* - - 曖昧さに気づかない
- 乖離が発生
- - 考えが明確化
- コードを生成
:::
正しい記法
:::{list-table}
:header-rows: 1
:widths: auto
* - 従来の課題
- SDD
* - 曖昧さに気づかない
- 考えが明確化
* - 乖離が発生
- コードを生成
:::
太字見出し + 箇条書きグループの表化
太字見出し + 箇条書きのグループが複数並ぶパターンは {list-table} に変換する。セル内箇条書きは * - - item の3段ネスト (行開始 → セル開始 → 箇条書き項目)、同一セル内の後続項目は4スペースインデントの - item。
禁止パターン
**カテゴリA**
- 項目1
- 項目2
**カテゴリB**
- 項目3
- 項目4
正しい記法
:::{list-table}
:header-rows: 1
:widths: auto
* - カテゴリA
- カテゴリB
* - - 項目1
- 項目2
- - 項目3
- 項目4
:::
左右分割レイアウト
1スライドに収まらない場合・説明と図を並べる場合・複数トピックを比較する場合は {list-table} で左右に分割する。
:header-rows: 0 :widths: 50 50 を基本とする (60 40 等で比率調整可)- ディレクティブのネストはコロンフェンスの段数で表現する (外側
:::::、内側 :::)
禁止パターン
1スライドに収まらない量の説明と図を、分割せずに縦へ積まない:
### アーキテクチャ
- 説明の箇条書き1
- 説明の箇条書き2
- 説明の箇条書き3
:::{mermaid}
flowchart TD
A --> B
:::
正しい記法
:::::{list-table}
:header-rows: 0
:widths: 50 50
* - - 箇条書き項目1
- 箇条書き項目2
- :::{mermaid}
flowchart LR
A --> B
:::
:::::
コード
- 外部ファイルに存在するコードは
{literalinclude} で取り込む。インラインへの複製は禁止
- 説明用の5行以下のコード片のみインラインコードブロックを許容する
:language: を必ず指定する
禁止パターン (外部ファイルのコードをインライン複製)
```python
def hello():
print("Hello")
```
正しい記法
:::{literalinclude} examples/hello.py
:language: python
:start-after: # start example
:end-before: # end example
:::
Mermaid ダイアグラム (sphinx-oceanid 導入時のみ)
extensions に sphinx_oceanid がある場合に適用する。
- フロー・シーケンス・状態遷移などの図は
{mermaid} ディレクティブで記述する。罫線文字や ASCII アートによる図は使用禁止
- 対応タイプ:
flowchart / graph (方向: LR, TD, TB, RL, BT)、sequenceDiagram、stateDiagram-v2、classDiagram、erDiagram、xychart-beta
- 非対応タイプ (
pie, gitGraph, mindmap, gantt 等) はビルド時に警告が出るため使用しない
:name: は本文から相互参照する場合のみ付与する- 縦方向に長い図 (
flowchart TD 等) はスライドからはみ出しやすい。高さ制約の対処は revealjs-config スキル参照
禁止パターン
┌─────────┐
│ Specify │
└────┬────┘
↓
┌─────────┐
│ Plan │
└─────────┘
正しい記法
:::{mermaid}
flowchart TD
A[Specify] --> B[Plan]
:::
Admonition
- 重要な情報・注意点・補足は Admonition ディレクティブで記述する。プレーンテキストで「注意:」「ヒント:」と書かない
- 使用可能なタイプ:
note / tip / warning / important / seealso
- スライドの表示領域は狭い。コンテンツは1〜3行に簡潔にまとめる
禁止パターン
注意: この操作は取り消せません
正しい記法
:::{warning}
この操作は取り消せない
:::
定義リスト
用語や概念の説明は定義リスト構文で記述する。箇条書きの - **用語**: 説明 で代用しない。
禁止パターン
- **SDD**: 仕様駆動開発。仕様書を起点にコードを生成する手法
正しい記法
SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法
一般ルール
コロンフェンスの統一
ディレクティブの囲みにはコロンフェンス (:::) を使用する。バッククォートフェンス (```) でディレクティブを囲まない。
禁止パターン
```{note}
バッククォートフェンスで囲んだディレクティブ
```
正しい記法
:::{note}
コロンフェンスで囲んだディレクティブ
:::
はみ出しの確認
スライドからのはみ出しは目視でしか検出できない。ビルド + プレビュー (sphinx-build スキルの revealjs / livehtml) で確認し、はみ出したらスライドを分割する。
関連スキル
- 姉妹スキル:
myst-authoring (汎用 MyST ルール)
- 連携:
revealjs-config (Mermaid の高さ制約等、設定側の対処)、sphinx-build (プレビューによるはみ出し確認)
