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.