القائمة
sphinx-revealjs の conf.py 設定(プラグイン・コードハイライト・テーマ・スライド寸法・表の中央寄せ・Mermaid 統合)の知識を提供するスキル。sphinx-revealjs プロジェクトでスライドの見た目や挙動を変更・修正するときに使用する。conf.py 編集の実行は sphinx-config に委譲する。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Sphinx ドキュメントの MyST Markdown 執筆支援スキル(ディレクティブ・ロール・相互参照・数式・sphinx-design)。extensions に myst_parser があるプロジェクトで docs/ 配下の .md を編集・作成するときや、MyST 記法について質問されたときに使用する。
sphinx-revealjs のスライドを MyST で書くための記法ルール(見出しレベルによるスライド分割、list-table、2 カラムレイアウト等)。extensions に sphinx_revealjs があるプロジェクトで docs/ 配下の .md を編集・作成するときに使用する。汎用 MyST 記法は myst-authoring が担当。
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-config |
| description | sphinx-revealjs の conf.py 設定(プラグイン・コードハイライト・テーマ・スライド寸法・表の中央寄せ・Mermaid 統合)の知識を提供するスキル。sphinx-revealjs プロジェクトでスライドの見た目や挙動を変更・修正するときに使用する。conf.py 編集の実行は sphinx-config に委譲する。 |
| license | MIT |
| allowed-tools | Bash, Read, WebFetch |
sphinx_revealjs があるプロジェクトで conf.py の revealjs 設定変更を求められた場合docs/conf.py の extensions に sphinx_revealjs が無い場合は明示的エラー伝播し、revealjs-init への誘導を案内する。
本スキルは「何を設定すべきか」の知識のみを持つ。conf.py 編集の実行 (バックアップ・復元・明示的エラー伝播) は sphinx-config スキルへ委譲する。
revealjs_script_plugins)src パスに _static/ プレフィックスは不要 (ビルダーが自動付加する)plugin.js — ES モジュール形式 (import 文を使用)。<script> タグでは動作しないhighlight.js 等 — UMD バンドル形式。<script> タグで読み込み可能src には必ず UMD バンドル版を指定するname は Reveal.js が認識するグローバル名を指定する# シンタックスハイライト
{"src": "revealjs/plugin/highlight/highlight.js", "name": "RevealHighlight"}
# スピーカーノート
{"src": "revealjs/plugin/notes/notes.js", "name": "RevealNotes"}
# 数式
{"src": "revealjs/plugin/math/math.js", "name": "RevealMath"}
# スライド内検索
{"src": "revealjs/plugin/search/search.js", "name": "RevealSearch"}
# ズーム
{"src": "revealjs/plugin/zoom/zoom.js", "name": "RevealZoom"}
revealjs_css_files)highlight.js は JS 側でコード構造を解析するのみで、色付けは CSS テーマが担当する。CSS テーマを読み込まないとハイライトは視覚的に反映されない。
revealjs_css_files = [
"revealjs/plugin/highlight/monokai.css", # ダーク背景
]
同梱テーマ: monokai.css (ダーク背景)、zenburn.css (ダーク背景・低コントラスト)
revealjs_style_theme)組み込みテーマ名またはカスタム CSS ファイル名を指定する。
revealjs_style_theme = "black" # 組み込みテーマ
revealjs_style_theme = "custom.css" # revealjs_static_path 配下のカスタム CSS
組み込みテーマ: black (デフォルト) / white / league / beige / night / serif / simple / solarized / moon / blood / sky
revealjs_script_conf)Reveal.js のデフォルトスライド幅は 960px で、ワイドスクリーンでは左右に余白が生まれる。
revealjs_script_conf = {
"width": 1200, # デフォルト: 960。ワイドスクリーンでは 1200 推奨
"height": 700, # デフォルト: 700
"slideNumber": "c/t", # 現在/総数 形式のページ番号
"hash": True, # URL にスライド位置を反映 (リロード・共有に強い)
}
同梱 reveal.js (5.x) の dist/reveal.css には次の規則があり、テーブルとコードブロックの margin を 0 にする:
html:not(.print-pdf) .reveal pre,
html:not(.print-pdf) .reveal table { margin-left: 0; margin-right: 0 }
この詳細度は (0,2,2)。テーマ側 (組み込み・カスタムとも) の .reveal table { margin: auto } は (0,1,1) で、CSS では読み込み順より詳細度が優先されるため、テーマの選択に関係なく対策しない限りテーブルは常に左寄せで表示される。
.reveal .slides section table で上書きすると詳細度 (0,2,2) の同点になり、テーマ CSS・追加 CSS は reveal.css より後に読み込まれるため上書き側が勝つ。
SCSS カスタムテーマ使用時は _sass/custom.scss に追記する:
.reveal {
.slides section table {
margin-left: auto;
margin-right: auto;
}
}
組み込みテーマのみの場合は _static/table-center.css を作成し、revealjs_css_files で読み込む:
/* Center tables within Reveal.js slides */
.reveal .slides section table {
margin-left: auto;
margin-right: auto;
}
revealjs_css_files = [
"revealjs/plugin/highlight/monokai.css",
"table-center.css",
]
なお同じ reveal.css の規則で pre の margin も 0 になるが、こちらは「コードブロックの幅最大化」の推奨値 (width: 100%) と整合するため上書きしない。
sphinx_revealjs.ext.sass)extensions に sphinx_revealjs.ext.sass を加えると SCSS からテーマをビルドできる。コンパイラは dart-sass バイナリで、初回ビルド時に GitHub Releases から自動ダウンロードされる (要ネットワークアクセス)。追加の Python 依存 (libsass 等) は不要。
extensions = [
"sphinx_revealjs",
"sphinx_revealjs.ext.sass",
]
revealjs_sass_src_dir = "_sass" # SCSS ソース
revealjs_sass_out_dir = "_static" # コンパイル先
revealjs_sass_auto_targets = True # _sass 配下を自動検出
revealjs_style_theme = "custom.css" # _sass/custom.scss のコンパイル結果
revealjs_static_path = ["_static"]
Reveal.js ベーステーマの pre はデフォルトで width: 90%、margin: auto。コンテンツ領域を最大化するには以下を上書きする:
.reveal {
.slides section {
padding: 10px; // デフォルトは 20px 程度
}
pre {
width: 100%;
margin-left: 0;
margin-right: 0;
box-sizing: border-box;
}
}
sphinx-oceanid は beautiful-mermaid (ELK.js ベースレイアウト) によるクライアントサイドレンダリングを使用する。Reveal.js の非表示スライド問題は IntersectionObserver と slidechanged イベントによる遅延レンダリングで自動的に解決される。
conf.py に "sphinx_oceanid" を追加するだけで動作し、追加設定は不要。
extensions = [
"sphinx_oceanid",
"sphinx_revealjs",
]
sphinx-oceanid では以下の設定・ファイルは不要:
mermaid_output_format, mermaid_cmd, mermaid_params 等の mermaid_* 設定puppeteer-config.json (Puppeteer は使用しない)mermaid-config.json (beautiful-mermaid がテーマを内包)sphinx-oceanid の SVG はデフォルトで height: auto のため、縦方向に長いダイアグラム (flowchart TD 等) がスライドからはみ出す。_static/oceanid-revealjs.css で max-height を設定し、revealjs_css_files で読み込む。
/* _static/oceanid-revealjs.css */
.reveal .slides .oceanid-diagram .oceanid-svg-container svg {
max-height: 500px;
}
revealjs_css_files = [
"revealjs/plugin/highlight/monokai.css",
"oceanid-revealjs.css",
]
# conf.py — sphinx-revealjs + sphinx-oceanid 構成例
extensions = [
"myst_parser",
"sphinx_revealjs",
"sphinx_oceanid",
]
revealjs_style_theme = "black"
revealjs_static_path = ["_static"]
revealjs_script_conf = {
"width": 1200,
"height": 700,
"slideNumber": "c/t",
"hash": True,
}
revealjs_css_files = [
"revealjs/plugin/highlight/monokai.css",
"oceanid-revealjs.css",
# SCSS 非選択時: "table-center.css" (「テーブルの中央寄せ」参照)
]
revealjs_script_plugins = [
{
"src": "revealjs/plugin/highlight/highlight.js",
"name": "RevealHighlight",
},
]
設定項目の網羅リストは WebFetch で公式ドキュメント https://sphinx-revealjs.readthedocs.io/en/stable/configurations/ から取得し、本スキル記載の知識 (落とし穴・推奨値) と組み合わせて提案する。
sphinx-config (conf.py 編集の実行)revealjs-init (プロジェクト未初期化なら誘導)revealjs-authoring (Mermaid の記法側ルール)