Link Tree#
About#
Similar but different from a Toc Tree.
Attention
This component is a work in progress. Breaking changes should be expected until a 1.0 release, so version pinning is recommended.
Problem#
So much work went into the toctree mechanics, it is sad that it is not a reusable component for building any kinds of navigation structures, and to be able to define its contents more freely.
Solution#
This component implements a programmable toc tree component, the link tree.
Details#
The link tree component builds upon the Sphinx toc and toctree subsystem. It provides
both a rendered primary navigation within the sde_linktree_primary context variable
for use from HTML templates, and a Sphinx directive, linktree, for rendering
navigation trees into pages, similar but different from the toctree directive. The
user interface mechanics and styles are based on Furo’s primary sidebar component.
Customizing#
Link trees can be customized by creating them programmatically, similar to how
the sde_linktree_primary context variable is populated with the default Sphinx
toc tree.
The section hidden behind the dropdown outlines how the “custom linktree” is defined, which is displayed at the bottom of the page in a rendered variant.
Custom linktree example code
import typing as t
from sphinx.application import Sphinx
from sphinx_design_elements.lib.linktree import LinkTree
def demo_tree(app: Sphinx, context: t.Dict[str, t.Any], docname: str = None) -> LinkTree:
"""
The demo link tree showcases some features what can be done.
It uses regular page links to documents in the current project, a few
intersphinx references, and a few plain, regular, URL-based links.
"""
linktree = LinkTree.from_context(app=app, context=context)
doc = linktree.api.doc
ref = linktree.api.ref
link = linktree.api.link
linktree \
.title("Project-local page links") \
.add(
doc(name="gridtable"),
doc(name="infocard"),
)
linktree \
.title("Intersphinx links") \
.add(
ref("sd:index"),
ref("sd:badges", label="sphinx{design} badges"),
ref("myst:syntax/images_and_figures", "MyST » Images and figures"),
ref("myst:syntax/referencing", "MyST » Cross references"),
)
linktree \
.title("URL links") \
.add(
link(uri="https://example.com"),
link(uri="https://example.com", label="A link to example.com, using a custom label ⚽."),
)
return linktree
Todo
Use the
linktreedirective to define custom link trees.Link to other examples of custom link trees.
Maybe use
:link:and:link-type:directive options ofgrid-item-carddirective.
Directive examples#
Example 1#
The link tree of the index page, using a defined maximum depth, and a custom title.
Appendix#
Here, at the bottom of the page, different global template variables are presented, which contain representations of navigation trees, rendered to HTML.
sde_linktree_primary: The classic toctree, like it will usually be rendered into the primary sidebar.demo_synthetic_linktree: A customized link tree composed of links to project-local pages, intersphinx links, and URLs, for demonstration purposes.
Hint
The corresponding template, linktree-demo.html will exclusively be rendered
here, and not on other pages.