메뉴
sphinx-revealjs のスライドを MyST で書くための記法ルール(見出しレベルによるスライド分割、list-table、2 カラムレイアウト等)。extensions に sphinx_revealjs があるプロジェクトで docs/ 配下の .md を編集・作成するときに使用する。汎用 MyST 記法は myst-authoring が担当。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Sphinx ドキュメントの MyST Markdown 執筆支援スキル(ディレクティブ・ロール・相互参照・数式・sphinx-design)。extensions に myst_parser があるプロジェクトで docs/ 配下の .md を編集・作成するときや、MyST 記法について質問されたときに使用する。
sphinx-revealjs の conf.py 設定(プラグイン・コードハイライト・テーマ・スライド寸法・表の中央寄せ・Mermaid 統合)の知識を提供するスキル。sphinx-revealjs プロジェクトでスライドの見た目や挙動を変更・修正するときに使用する。conf.py 編集の実行は sphinx-config に委譲する。
sphinx-revealjs によるスライド専用プロジェクトを初期化するスキル。docs/ が未作成のプロジェクトで発表スライドの新規作成を求められたときに使用する。依存追加・MyST テンプレート生成・テーマ選定・Makefile 整備までを行う。
既存の reStructuredText 製 Sphinx ドキュメントを rst-to-myst で MyST Markdown へ移行するスキル。実質的な RST コンテンツを持つプロジェクトの移行を求められたときに使用する(sphinx-quickstart の雛形だけの場合は対象外)。変換結果を検証してから元ファイルを削除する。
Sphinx ドキュメント・スライドを Makefile 経由でビルドするスキル(HTML・latexpdfja・EPUB・linkcheck・livehtml・revealjs)。ドキュメントやスライドのビルド・プレビュー・開発サーバー起動・リンクチェックを求められたときに使用する。パッケージマネージャ検出とビルドエラーの解釈は本文参照。
docs/conf.py を既存設定を保ちながら安全に更新するスキル。Sphinx 拡張の追加・削除、テーマ、プロジェクトメタデータなど conf.py の変更を求められたときに使用する。
| 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 を編集・作成する場合myst-authoring見出しレベルがスライド分割を決める:
# — タイトルスライド (文書内で1回のみ)## — セクション区切りスライド (横方向のスライド)### — 個別スライド (セクション内の縦方向のスライド)1スライド1トピック。1つの ### に複数トピックを詰め込まず、スライドを分割する。
### 機能紹介と導入方法と注意点
- 機能A の説明
- 機能B の説明
- インストール手順
- 設定方法
- 利用時の注意点
### 主な機能
- 機能A の説明
- 機能B の説明
### 導入方法
- インストール手順
- 設定方法
### 利用時の注意点
| col1 | col2 | 形式) は使用禁止。必ず {list-table} ディレクティブで記述する:header-rows: を必ず指定する (ヘッダ行がない場合は 0):widths: auto を基本とする| ツール | 特徴 |
|---|---|
| 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} で取り込む。インラインへの複製は禁止:language: を必ず指定する```python
def hello():
print("Hello")
```
:::{literalinclude} examples/hello.py
:language: python
:start-after: # start example
:end-before: # end example
:::
extensions に sphinx_oceanid がある場合に適用する。
{mermaid} ディレクティブで記述する。罫線文字や ASCII アートによる図は使用禁止flowchart / graph (方向: LR, TD, TB, RL, BT)、sequenceDiagram、stateDiagram-v2、classDiagram、erDiagram、xychart-betapie, gitGraph, mindmap, gantt 等) はビルド時に警告が出るため使用しない:name: は本文から相互参照する場合のみ付与するflowchart TD 等) はスライドからはみ出しやすい。高さ制約の対処は revealjs-config スキル参照┌─────────┐
│ Specify │
└────┬────┘
↓
┌─────────┐
│ Plan │
└─────────┘
:::{mermaid}
flowchart TD
A[Specify] --> B[Plan]
:::
note / tip / warning / important / seealso注意: この操作は取り消せません
:::{warning}
この操作は取り消せない
:::
用語や概念の説明は定義リスト構文で記述する。箇条書きの - **用語**: 説明 で代用しない。
- **SDD**: 仕様駆動開発。仕様書を起点にコードを生成する手法
SDD
: 仕様駆動開発。仕様書を起点にコードを生成する手法
ディレクティブの囲みにはコロンフェンス (:::) を使用する。バッククォートフェンス (```) でディレクティブを囲まない。
```{note}
バッククォートフェンスで囲んだディレクティブ
```
:::{note}
コロンフェンスで囲んだディレクティブ
:::
スライドからのはみ出しは目視でしか検出できない。ビルド + プレビュー (sphinx-build スキルの revealjs / livehtml) で確認し、はみ出したらスライドを分割する。
myst-authoring (汎用 MyST ルール)revealjs-config (Mermaid の高さ制約等、設定側の対処)、sphinx-build (プレビューによるはみ出し確認)