Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking
Lecture: How Sphinx linking works
Login or
purchase this course
to watch this video and the rest of the course contents.
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 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.