Static Sites with Sphinx and Markdown Transcripts
Lecture: How Sphinx linking works
0:00 So imagine we are in a Sphinx site and it's got two documents, first.rst and second.rst.
0:09 And you want to link to one from the other um in Sphinx with restructured text and one of the documents like the first document,
0:17 you might put some text and then this colon doc colon thing. And then in the back ticks you would put a link to the file name of
0:26 the second document. Now when you render, you'll see that the hyperlink actually has the title of the second document and we didn't
0:36 put it in the link text, which is something you'd have to do in markdown. And so it kind of makes you wonder, hey, what's going on here?
0:42 There's no link text. And that turns out to be kind of the power of sphinx. It keeps kind of a database of all the documents in your sight and
0:52 everything that is linkable targets and it keeps the path and the title of all of the documents and resources. So that when you make a link,
1:03 it can insert the title and update the title in the link text. If you change the targets title,
1:12 it's not just for documents in this example we did colon dot colon. But if you did colon ref colon, you could point to a location that was a role.
1:23 target somewhere in a document for example, a section heading. And then one other thing that Sphinx can do in addition to
1:33 providing you the link text and deep linking into a document is it will warn you
1:39 if you link to something that doesn't exist and that's really not something you can get from some of these other static site generators.
1:47 And it's really valuable. It's something that is worth looking at if you're doing a static website and markdown.