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.
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.