nikkie-ftnextの日記

イベントレポートや読書メモを発信

Sphinxで作ったスライドをNotionでも公開するのを狙って、sphinx-notionという拡張を始めました

Sphinx

はじめに

七尾百合子さん、お誕生日 35日目 おめでとうございます！ nikkieです。

前回のリリース報告エントリで予告した、自作ライブラリsphinx-notionについての記事です。

どういったSphinx拡張かというのは思い出す必要があり（ドキュメントも整えたい！）、別に記事を書くつもりです。

目次

sphinx-notion

reSTで書いたSphinxドキュメントをNotionにもアップロードしたいな〜と始めました。

拡張を有効にすると、notionビルダーでビルドできます。

# conf.py
extensions = [
    "sphinx_notion",
]

% make notion

ビルドされるのは、Notion API向けのJSONファイルです（build/notion/にできます）。
これをNotion API経由でアップロードすることで、reSTファイルと同じ内容のNotionページとなります！
アップロードスクリプト：https://github.com/ftnext/sphinx-notion/blob/5ae803eebb35d1eafeb3d258009f03db683f0dd1/upload.py

動作例（ただしv0.0.1）

1つreSTファイルを置きました

.
├── build/
├── source/
│   ├── conf.py
│   └── index.rst
└── Makefile

ビルドでできたbuild/notion/index.jsonをNotion APIにアップロードしてできたページはこちらです。

なお、対応ディレクティブは限定的です（v0.0.1ですから！ プルリクは大歓迎です）
https://github.com/ftnext/sphinx-notion/tree/0.0.1/tests/roots

またmyst-parserを使ってMarkdownを試したのですが、リンクのサポートが残っています。
<>で囲まないといけないようですね（うーむ）
https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#markdown-link-syntax

なぜ作ったか？

私はsphinx-revealjsを使って、reSTを書いてスライドを作っています1。
スライドはGitHub Pagesで公開している2のですが、同じ内容をNotionの1ページ版としても公開できるよなと思いつきました。

1年くらい前、Notion APIを触っていた時期に着想しました。

サポートするディレクティブを追加しながらTDDでの開発は、着実に進んでいる感があり楽しかったですね

Sphinxは同じ原稿がビルダーの違いでHTMLにもPDFにもできるので、スライドのreSTがNotionページにもできて個人的には大満足です3。

終わりに

sphinx-notionの公開を受けて、どんなSphinx拡張か、なぜ作ったかを記事にしました。
同じ原稿でもビルダーによって異なる出力にできるというのが私にとってSphinxの魅力であり、ほしかったNotionページ出力を追加できてとても楽しいです。
自分のニーズに合わせて細々と拡張していくと思います

  1. 自作拡張と合わせて使っています ↩
  2. ↩
  3. Reveal.jsスライド版 https://ftnext.github.io/2025-slides/practice/slide.html↩