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:06
just rolls. First if you really liked that thing about linking to a heading but you
0:14
find it too much work to preface all of your headings with that syntax for a
0:19
link, MyST has a setting for auto generating header anchors from the heading words.
0:30
And this can make it very convenient to just get that for free everywhere that you
0:35
use a heading. But I consider it a little bit iffy because those identifiers
0:41
don't prove to be all that stable.
0:43
Remember they're going to be published as part of your website and outside people might be
0:49
linking to it as well. And if you decide to change the wording of one
0:53
of your headings, then all of your roles and all of your external links will
1:01
be broken. It's just not a very stable identify.
1:03
Sphinx is known for documentation and it's auto doc tool generates all kinds of linkable
1:10
targets in your source code.
1:12
We're going to have a section devoted to documentation and auto doc but for now just
1:18
understand that you point something like Sphinx at a big pile of code and it not
1:25
only turns it into words and highlighting on the screen,
1:29
it turns it into structure including roles.
1:34
Linkable targets that can be pointed to as stable,
1:38
identifiers from within your narrative documentation.
1:43
We've seen a little bit about the toctree directive and it gets your files listed
1:48
in a certain order but it also helps on linking because thanks to the order in
1:55
the nesting, it will generate previous and next links that you can use in your
2:00
templates as well as up to go up A level and top to go all the
2:06
way to the top and finally linking to external URL's that aren't managed by Sphinx
2:11
that's a part of your website.
2:14
But how are you going to find out if those links are broken,
2:17
Sphinx ships with a tool that you can use and run make link check.
2:22
And it will go through your built documentation and try to find any places that point
2:29
to a URL on the web, which no longer works