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,
0:05 first.rst and second.rst.
0:08 And you want to link to one from the other um in Sphinx with restructured text
0:14 and one of the documents like the first document,
0:16 you might put some text and then this colon doc colon thing.
0:20 And then in the back ticks you would put a link to the file name of
0:25 the second document. Now when you render,
0:29 you'll see that the hyperlink actually has the title of the second document and we didn't
0:35 put it in the link text,
0:37 which is something you'd have to do in markdown.
0:39 And so it kind of makes you wonder,
0:40 hey, what's going on here?
0:41 There's no link text. And that turns out to be kind of the power of
0:46 sphinx. It keeps kind of a database of all the documents in your sight and
0:51 everything that is linkable targets and it keeps the path and the title of all
0:58 of the documents and resources. So that when you make a link,
1:02 it can insert the title and update the title in the link text.
1:08 If you change the targets title,
1:11 it's not just for documents in this example we did colon dot colon.
1:16 But if you did colon ref colon,
1:18 you could point to a location that was a role.
1:22 target somewhere in a document for example,
1:26 a section heading. And then one other thing that Sphinx can do in addition to
1:32 providing you the link text and deep linking into a document is it will warn you
1:38 if you link to something that doesn't exist and that's really not something you can get
1:43 from some of these other static site generators.
1:46 And it's really valuable. It's something that is worth looking at if you're doing a static website and markdown.