Static Sites with Sphinx and Markdown Transcripts
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