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.

Talk Python's Mastodon Michael Kennedy's Mastodon