Static Sites with Sphinx and Markdown Transcripts
Chapter: More Authoring
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.