Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking between sites
Lecture: Linking to remote documents
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
We have a static website and we're riding content that has rich linking within that website Now that we've set up
0:10
Inter Sphinx we can link to content on the Sphinx site as if it were local Let's see this in action first.
0:19
I want to demonstrate a full build of Sphinx from the command line so you can see the output that gets the inventory file from the Sphinx website.
0:33
So when I run the Sphinx build command a lot of the output that it dumps to the console and that includes loading inter sphinx inventory from the
0:48
URL. We specified up in the conf file so that's what it's doing behind the scenes is it checks to see if it has any of these objects.inv
1:00
files that need to be downloaded, retrieves them and associates them with a key of Sphinx. Now back in my about us document.
1:13
I might want to link to something that says we're using Sphinx and we're using Sphinx roles and how powerful they are.
1:23
So I could do it the traditional external link way with markdown where you put the link text and then you put a.
1:32
URL. But that doesn't give me any of the sphinx goodness. First you know that's a long. URL. But what if we typed it wrong?
1:41
Would we get any warnings? No we would have to run some link checker. What if the link what if the Sphinx stocks get reorganized so that it's not at
1:51
that location anymore. It's at some other location. Well with roles. You can hide the internal structure just by putting a semantic label
2:00
on things. And wouldn't it be great to apply that to external content and then
2:07
finally it's no fun thinking about this link text which might change and get out of
2:12
date with what the remote page says is the meaning of that link target. Now the first of the three of these points can be solved with a separate link
2:23
check but it's more work and won't help with some of this more semantic stuff. So let's take a look at how we would do this with a sphinx roll.
2:33
Thanks to 'interphinx'. So first thing I'll do is delete this really long URL . I'll leave the link text in there.
2:44
But all I need to say now is that prefix that I had in the conf file, a colon and then the role that I'm pointing to.
2:55
So I will save that and I'll go back to my browser and I'll look at the bottom of my about us page and I'll see that I now have a link
3:13
that takes me to this. URL. I didn't have to memorize some really long H to blah blah blah. And in fact if I go back to my text I can
3:24
do what you hope we could do which is leave out the link text and let the content on the other end hand over the title.
3:36
Save it go back to my document in the browser, see what it reloaded as. And it gave me the link text of the thing
3:47
that I was linking to. What we also saw was that I wasn't linking to a remote document in its title.
3:57
I was linking a deep link into a section in the remote document and getting the
4:04
link text from that section heading now as wrap up and as a reminder if you link to something that is broken,
4:13
if I put this then my sphinx build would actually warn me that I have a broken link if I linked to this but the remote side changed it.
4:26
I would also get a warning saying that I link to something that doesn't exist.
4:30
This is something that really doesn't exist in other static site generators and is a very useful tool.