Add "link tree" element, using directive linktree
#11
Conversation
| def demo_tree(builder: Builder, context: t.Dict[str, t.Any], docname: t.Optional[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(builder=builder, 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"), | ||
| # rST link syntax. | ||
| ref("myst:syntax/images_and_figures", "MyST » Images and figures"), | ||
| ref("myst:syntax/referencing", "MyST » Cross references"), | ||
| # MyST link syntax. | ||
| # ref("myst#syntax/images_and_figures"), # noqa: ERA001 | ||
| ) | ||
|
|
||
| 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 |
There was a problem hiding this comment.
This is how you would currently define a link tree, which will effectively render into a HTML/CSS primary navigation menu using Furo's furo.get_navigation_tree().
In the future, there will be the possibility to define a linktree inline, using markup, just like a toctree. What you can see here is just the first version of a possible Python API for that.
/cc @matkuliak, @msbt, @nomicode
Codecov Report
@@ Coverage Diff @@
## main #11 +/- ##
===========================================
- Coverage 94.44% 75.72% -18.73%
===========================================
Files 6 9 +3
Lines 180 449 +269
===========================================
+ Hits 170 340 +170
- Misses 10 109 +99
Flags with carried forward coverage won't be shown. Click here to find out more.
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
| The link tree of the `index` page, using a defined maximum depth, and a custom title. | ||
| ```{linktree} | ||
| :docname: index | ||
| :maxdepth: 1 | ||
| :title: Custom title | ||
| ``` |
There was a problem hiding this comment.
Needs to be completed by using a custom MyST markup to define the content items of a linktree element.
About
Add a
linktreedirective, and a corresponding "Link Tree" web element. It is similar but different from a classic Sphinx toc tree. Instead, it is meant to be a programmable toc tree component.Most importantly, allow users to compose their link trees more freely, using any of the listed link item types, and maybe more.
Discuss
linktreedirective #14Preview
Visually
The visual appearance can be inspected on the RTD preview page.
https://sphinx-design-elements--11.org.readthedocs.build/en/11/linktree.html
Install
The package can be directly installed from the development branch.
Appearance
References