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