Welcome to sphinx-better-subsection’s Documentation!#
Better your Sphinx section IDs.
This extension helps keep your permalinks permanent by allowing you to specify a section’s ID. As an example:
.. _v1.2.3:
v1.2.3 (2022-03-19)
-------------------
The permalink on the title will be #v1-2-3 instead of
#v1-2-3-2022-03-19. When you change the section title later on, the
permalink will still work.
Installation#
Download and install this extension using pip:
$ pip install sphinx-better-subsection
Then add this extension in your conf.py:
extensions += ["sphinx_better_subsection"]
Usage#
Add a reST internal hyperlink target (the .. _name: syntax) before your
section. This extension moves that ID to the front of the IDs list, making the
permalink the target’s ID instead of the generated ID from the title. When
multiple are found, the last one is used.
This enhances existing reST to do the expected thing and also degrades gracefully when this extension isn’t used (such as in GitHub or online renderers).
Docutils#
This package provides a docutils transformer called PreferSectionTarget
(subclass of docutils.transforms.Transform) usable via:
from sphinx_better_subsection import PreferSectionTarget
document.transformer.add_transform(PreferSectionTarget)
MyST#
As far as I can tell, this extension is compatible with MyST using its
header target syntax (the (name)= syntax). The first example in
MyST would be:
(v1.2.3)=
## v1.2.3 (2022-03-19)
Links#
Source Code: https://github.com/GeeTransit/sphinx-better-subsection
Documentation: https://geetransit.github.io/sphinx-better-subsection/
PyPI Releases: https://pypi.org/project/sphinx-better-subsection/