Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking
Lecture: Markdown linking

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

Talk Python's Mastodon Michael Kennedy's Mastodon