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