Static Sites with Sphinx and Markdown Transcripts
Chapter: Simple Markdown
Lecture: Images
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
Markdown really is a simple syntax,
0:03
gets a lot of things, right.
0:05
One of the things that really gets right is images.
0:08
Let's take a look at how you can use markdown image syntax for your images in
0:14
Sphinx. I'm back in the About us document and I'd like to add a little
0:21
section. It says something cool about the usage of Python,
0:25
Schlockchain and I want to include the python logo and I want to do that
0:32
just after this paragraph. So I'll put a blank line in and I'll paste in
0:37
some text. And this looks a lot like the link syntax that we just saw
0:42
from Markdown. It's got the URL in parenthesis in this case it's the
0:47
URL to the Python logo as a PNG file and it's got some text
0:53
in square brackets. In this case it will be the alt text for an image
0:57
But we're telling Mark down this is an image by putting the exclamation point,
1:03
the exclamation point in front. I get a preview in my tool that shows the
1:10
rendered image and when I save and Sphinx runs MyST,
1:14
converts that into an image that is displayed in line using the URL to.
1:21
That logo. Now, that's going to have visitors retrieve the image from the Python
1:28
site every time maybe you want to have a local image.
1:32
Let's do that instead. Let's go to the terminal and let's run 'wget' to
1:37
go download the Python logo to something local and now what I can do instead of
1:43
providing the full URL.
1:46
I can just say get python-logo,
1:49
which is here in my file system as python-logo,
1:55
right beside the markdown file that we're editing and when I save my tool previews the
2:03
markdown correctly, but also it still works when rendered in Sphinx.
2:09
in markdown more specifically what it's going to do is take that file that's on disk
2:16
here and it's going to copy it into the build output into the target of html
2:21
that we're building towards. And there's now a subdirectory called images with all the images
2:27
They're part of our content.
2:29
And when I look in there I will see this file python-logo,
2:33
the 'AboutUs.html' file that was just built We'll have a URL
2:39
that's relative to go up and down into images to point at that logo file just
2:48
to ramp up and show one last part of this markdown syntax,
2:51
If I made a mistake in the file name,
2:55
we'll see that the all text is displayed in place of the image.
3:00
This is the simple image syntax using the existing markdown image syntax as we'll see in
3:08
later sections, MyST has a much more interesting,
3:12
much more useful, much more powerful syntax that taps into the underlying Sphinx directive for images.