Static Sites with Sphinx and Markdown Transcripts
Chapter: More Authoring
Lecture: Images
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
Images are an important part of authoring and MyST gives us some interesting ways to express
0:08
ourselves via images via markdown. We'll take a look at some of the syntax for
0:14
images in markdown. Thanks to MyST and introduce some new cool things and MyST along
0:21
the way. We previously showed the syntax in MyST for remote and local images. The second syntax has all the cool Sphinx stuff that you would expect.
0:35
It processes the image, copies it to the build directory, makes a relative URL inserts in the text etcetera.
0:42
But Sphinx can do a lot more with images and there's lots of options if you take a look at the Sphinx docs.
0:47
The image directive is really just a thin wrapper around restructured text which lets you do a lot of processing on the image.
0:58
How can we tap into some of that from syntax? That's an alternative to the markdown syntax back in the editor.
1:09
We just want to make sure that everything is working with our live reload server.
1:14
I'm gonna just type Hello and I'm gonna save it go over my browser which is pointed at this page getting rendered. I do see Hello. So I'm back to life.
1:24
I can delete this and I'm gonna convert this simple markdown syntax to a MyST syntax using a code fence to insert the image,
1:36
thus letting me tap into the underlying Sphinx directive. So I'll start with a triple back tick and instead of a language,
1:42
I'm going to put curly braces, which means the next thing is the directive and directive can have an argument which is
1:48
the file name. And then you can pass options to this. I'll paste them in to speed things up,
1:55
but we can have Python logo just as like we have in the square brackets. We can put a CSS class,
2:01
a width and alignment to say how it should appear on the page. And when I save and go back over and take a look,
2:10
I see the original one and then I see the second one which is aligned and 200 pixels wide. Now we can also do something even cooler.
2:19
HTML has a figure element which puts kind of the image and some text that goes with it into a box that you can control.
2:28
And this is also supported in Sphinx and restructured text. So let's take a look at what the syntax for that looks like.
2:36
What we're gonna use this time is an optional MyST syntax. And these are things that you have to turn on in the conf file.
2:44
We're gonna use colon fence for this. So back in my IDE. I'll go to the conf file and see that I've got this enabled as an extension
2:56
of the colon fence extension which lets me now type in the figure using a colon fence instead of a code fence.
3:06
I just pasted this in and you can see that it's got triple colons instead of
3:10
triple back ticks. And it's got a directive with an argument and some options and then a body. The body has just a regular HTML image tag for the image
3:21
asset and then some markdown that goes with it. Let's go through a couple of these points.
3:26
Well first we'll just go ahead and save it and let it render and I go over to my browser, look at the bottom of my page and see that I've
3:34
got a richer image now that has some body that goes with it, but that's not all. Let's take a look first at why we want this
3:45
triple colon instead of triple back tick. If I go and look at how markdown tooling, such as previews and editors will treat it.
3:57
The first one is just rendered with everything inside the code fence. In a big block. The second one has some of it that's rendered in a
4:07
way that of course this preview isn't gonna know what to do with this markdown MyST specific stuff but the part that is marked down,
4:16
it can go ahead and render it and show it to you. So for example, I could put in a bulleted list and it would handle that
4:25
correctly if I took this for example and tried to put it as the body of this code fence is just gonna go right in the middle of the big blob.
4:37
So that didn't work correctly either. One last point that really taps into some power that we're going to see later,
4:43
is this argument is no longer the image file name. It's a role. It's something that is linkable within any documentation in Sphinx
4:56
and therefore in MyST. So for example, if I went back to my index file and put in some text that linked to it, go back to the rendering of it,
5:10
go to the top level page. I see that I now have a link to that figure and it extracted the title
5:19
of the figure from the text that was in the figure element. I can click on it and jump directly to that figure.
5:29
Why is all that possible? Because the code fence, the colon fence that we used allowed us to specify a linkable role.