Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking
Lecture: More on linking
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
As you can imagine there's a lot more linking power in Sphinx beyond.
0:07
just rolls. First if you really liked that thing about linking to a heading but you
0:15
find it too much work to preface all of your headings with that syntax for a
0:20
link, MyST has a setting for auto generating header anchors from the heading words.
0:31
And this can make it very convenient to just get that for free everywhere that you
0:36
use a heading. But I consider it a little bit iffy because those identifiers don't prove to be all that stable.
0:44
Remember they're going to be published as part of your website and outside people might be
0:50
linking to it as well. And if you decide to change the wording of one of your headings, then all of your roles and all of your external links will
1:02
be broken. It's just not a very stable identify. Sphinx is known for documentation and it's auto doc tool generates all kinds of linkable
1:11
targets in your source code. We're going to have a section devoted to documentation and auto doc but for now just
1:19
understand that you point something like Sphinx at a big pile of code and it not only turns it into words and highlighting on the screen,
1:30
it turns it into structure including roles. Linkable targets that can be pointed to as stable, identifiers from within your narrative documentation.
1:44
We've seen a little bit about the toctree directive and it gets your files listed
1:49
in a certain order but it also helps on linking because thanks to the order in
1:56
the nesting, it will generate previous and next links that you can use in your templates as well as up to go up A level and top to go all the
2:07
way to the top and finally linking to external URL's that aren't managed by Sphinx that's a part of your website.
2:15
But how are you going to find out if those links are broken, Sphinx ships with a tool that you can use and run make link check.
2:23
And it will go through your built documentation and try to find any places that point to a URL on the web, which no longer works