🧭

Sphinxに「トップに戻る」ナビゲーションをつける

2025/01/13に公開

自サイトがSphinx製なのですが、たまに長めのページが存在します。
テーマによっては、前後のページへのリンクが最下部に出力されることはあるのですが、ものによっては無いこともあります。

そうなってくると、楽にページトップに戻りたくなるもの。
というわけで、そんなSphinx拡張を作ってみました。

何を作ったんですか?

atsphinx-goto-topというPythonプロジェクトです。

https://pypi.org/project/atsphinx-goto-top/

Sphinxで生成されるHTMLに「トップに戻る」機能を持つボタンを生成します。
下の動画は、自分のサイトで有効にしている動作のデモです。

https://www.youtube.com/watch?v=fYzJOI5Ni94

シンプルな使い方

例によって試すだけなら非常にシンプルです。

PyPI上で公開しているので、シンプルにpip経由でインストールするだけ。

pipを使ったインストール例
$ pip install atsphinx-goto-top

追加のオプション無しに、拡張として登録するだけで平気です。

conf.py
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を使って、ボタンの表示を適切なスタイルに調整する。

展望

当面やりたかったことがあらかた実現できたので、バンドルされている内容の調整をしたらしばらくは普段遣いする感じになりそうです。
もし興味があるなら使ってみてください。

脚注
  1. 自サイトの例では、「ボタンのデザインをテーマに合わせる」「ページ上部にいたら表示しない」「フッターには被せない」という調整をしています。 ↩︎

  2. いわゆる空のフラグメントだけを指定したリンクを用意して、クリック時に即時ジャンプする感じのもの。 ↩︎

  3. extraheadはHTMLビルダー内でならまず使われる、「<head>要素内に追加で要素を挿入したいとき」に使うコンテキスト変数。 ↩︎

GitHubで編集を提案

Discussion