Sphinxに「トップに戻る」ナビゲーションをつける
自サイトがSphinx製なのですが、たまに長めのページが存在します。
テーマによっては、前後のページへのリンクが最下部に出力されることはあるのですが、ものによっては無いこともあります。
そうなってくると、楽にページトップに戻りたくなるもの。
というわけで、そんなSphinx拡張を作ってみました。
何を作ったんですか？
atsphinx-goto-topというPythonプロジェクトです。
Sphinxで生成されるHTMLに「トップに戻る」機能を持つボタンを生成します。
下の動画は、自分のサイトで有効にしている動作のデモです。
シンプルな使い方
例によって試すだけなら非常にシンプルです。
PyPI上で公開しているので、シンプルにpip経由でインストールするだけ。
$ pip install atsphinx-goto-top
追加のオプション無しに、拡張として登録するだけで平気です。
extensions = [
# 適当なこの辺りに追加
"atsphinx.goto_top",
]
この状態でビルドすると、ページの右下に「Back to top」というテキストボタンが表示されるようになります。
オプションとか
テーマによってはこの状態だと使いづらい可能性もあるので、いくつかオプションを用意しています。
すぐ試せるものを挙げると、このようなことが出来ます。
-
goto_top_design: ボタンのデザインを切り替える。"image"を指定すると、アイコンを使ったボタンになる。 -
goto_top_side: ボタンの表示位置を変更する。"left"にすれば、左下に表示される。
意図的にカスタマイズの余地を残しているので、もし気になるならドキュメントを参照してください。 [1]
内部実装にまつわる話
いくつか見たサイトには、フッター部分にリンクとして「トップに戻る」が実現されています。 [2]
Sphinxテーマ上での実装だと何かしらのテンプレートにボタンを追加して終わりではあります。
一方で、汎用的な拡張として実装するとそもそもテンプレートへの出力が出来ません。
そのため、次のようなプロセスを取ることで、「どんなテーマでも動作する」ようにしています。
-
html_js_filesに専用のJavaScriptを、html_css_filesに専用のCSSを登録する。 - 出力予定のボタンは、
<template>要素として用意したうえで、extrahead[3] として<head>要素内に出力する。 - 専用JSは、ロード時に上記の
<template>を下に<body>要素内へボタンを挿入する。 - 専用CSSを使って、ボタンの表示を適切なスタイルに調整する。
展望
当面やりたかったことがあらかた実現できたので、バンドルされている内容の調整をしたらしばらくは普段遣いする感じになりそうです。
もし興味があるなら使ってみてください。
Discussion