Static Sites with Sphinx and Markdown Transcripts
Lecture: Markdown linking
0:00 Markdown has a simple syntax for linking.
0:04 It's one of the things that's attractive about markdown versus restructured text,
0:09 people writing in Sphinx usually get frustrated because the linking syntax is a little bit clumsy
0:15 and you can't really remember, you always have to look it up.
0:18 Let's see the simple markdown linking syntax in action and see how it taps into the
0:26 underlying Sphinx linking on the index page.
0:30 We'd like to link to the about us page in a sentence and use simple normal
0:39 markdown linking along the way. So I'll start by putting some sentence text and then
0:45 I want to do the link and I'll do the normal markdown approach linking and if
0:53 I wanted to I could, you know,
0:56 preview this and a tool and it would give me the kind of rendered output.
1:03 But I can also go over to my browser and see what it did with it
1:07 And I see that I've got a normal hypertext link with about us as the
1:13 link text, so it looks just like normal markdown.
1:18 But if I do a couple of things to show that it's got the power of
1:21 Sphinx underneath. For example, I'm going to turn on the the run live reload
1:29 command tool that that we introduced earlier and I'm gonna put in an error.
1:34 I'm going to link to something that doesn't exist and when I save,
1:39 I'll see that I've got a warning that we referenced a Target about us X.
1:45 That doesn't exist and that's something you don't get from most markdown based static site generators
1:50 Another thing you don't get from them is the ability to get the link text
1:58 from the title of the target from about us so that I don't have to do
2:02 the extra work to type it.
2:04 And if it changes in the future,
2:05 I don't have to go all through my site changing it.
2:08 So I'm going to remove the link text from the square brackets and then when I
2:13 go and take a look, I see that it has rendered as about us.
2:18 I can prove that it's getting the link text from the title by going over to
2:23 about us and changing this to say about us really.
2:29 And when I go back to my browser,
2:31 I see that it's automatically updated the link text for that link and any other links
2:39 that point to about us. And one last thing that's really cool about it is
2:45 this all works not just with html but with pdf rendering and main page rendering and
2:50 any custom kinds of builders that you might write.
2:53 This system of using simple markdown text of square brackets and parenthesis and then tapping into the underline power of Sphinx.