Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking
Lecture: Headings and roles
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
We just saw how to link to a document but can we link to a spot within a document, like a heading or even just some arbitrary location Sphinx has a
0:14
way to insert. We'll call the markers in documents and these markers can mean many things, one of which they can provide linkable targets.
0:25
And so these markers, which Sphinx calls roles can be written as colon, then role name and then the back tick and then the content for that role.
0:37
And so for example, I could just say roll target somewhere and then I've created a new spot in the links,
0:46
the Sphinx system of linking. I've created a new target that other things can link to and even get things like the title text.
0:55
And we'll show in this example a way of linking to a section and having the section title be used as the link text. With roles
1:10
It makes it really easy to have stable intuitive deep links in your website,
1:16
which frees your links from using file names at paths and have something a lot easier
1:22
to remember. A lot easier to fix if you reorganize your file names and directory
1:28
names and things like that and they have semantic meaning rather than whatever you might have used for the file name. So back in about us,
1:37
I want to add a section, it talks about our investors. It's going to put in some text,
1:43
normal markdown stuff that's going to be an H2 because it has double pound hashtag
1:49
and then some a paragraph that could have other paragraphs and the whole thing would be considered a single block kind of a section.
1:56
And I'd like that section to be linkable deep linka ble within the document from other places in my website.
2:06
And the the MyST syntax for doing this in markdown is pretty simple. I want to just say investors. I don't want to have to say the name of the file.
2:15
I don't want to have to put some special sequence in order to deep link down into it. And so I'm gonna say investors and I have now added a role
2:26
called investors. And so anything that wants to link to it can link to the
2:30
role. It will scroll down directly to this and it's actually a structural part of the site. It has meaning that can be put to work in various cases.
2:40
And so now if I go back to my homepage and I'd like to give information about our investors, I start typing a sentence and I can say ref to tap
2:56
into the ref directive using a curly brackets and then back tick in the name of the role and I'll save that.
3:05
And we saw this syntax previously about having a role in in the middle of a sentence an in line kind of thing.
3:15
And the role is just I'm sorry the directive is just curly brackets directive name. We used it for download links now when I go over to the browser,
3:26
I go to the homepage, I see that it has linked to the page but look at the URL. Down at the bottom.
3:36
It's going to say investors to deep link all the way down to that section heading
3:42
and it's taking the as link text is taking the name of the heading that I provided. Let's take a look at that again.
3:49
I'm gonna change the heading and it's automatically going to change the link text.
3:57
I'll change this to our investors And when I save I didn't have to go back over to all the things that link to it and provide new link text.
4:07
They're all updated because they're all pointing to that role. If I go back to the browser, I see that I've gotten my updated link text.
4:19
So just as a review what Sphinx is doing here. Thanks to MyST and Markdown syntax, it's finding the role definition for investors.
4:30
It will warn if that role doesn't exist if it does exist, it will get the link text from the heading just after the role.
4:41
It will generate a link to that document with that link text and it will put an internal anchor to scroll down to that section.
4:53
Just as one last point on this. You can also inside here override the link text. If you want to provide your own link tag.