Static Sites with Sphinx and Markdown Transcripts
Chapter: Simple Markdown
0:00 Let's take a look at some markdown formatting as it surfaces in Sphinx via MyST.
0:07 We'll do some simple formatting in this step will do some headings and paragraphs and character styling and lists and things like that.
0:17 I have my editor on the screen with my markdown on one side. The editors markdown preview on the other side and then I've got my live reload server
0:27 on this side with the web page. So what we have first is I can add some Headings. For example, we've got about us.
0:36 I could change it to an H3 and as I save you can see the preview shows a smaller one. This is formatted differently because it is the title of
0:48 the page. If I reverted that and said heading 3 and saved. Once the library loads server ran, you'd see that I get a different heading style.
1:01 I can also do some inline styling. I'll make a new paragraph just by having a blank line. I say we are a bold company.
1:10 Yes, we are and we are innovative. And these use of the asterix. The first one is bold as you can see in the preview.
1:20 Second one is italics as you can see in the preview when I save in the
1:24 live reload server runs, we see that the rendering gets the bold and the innovative as well. Let's say I want to do.
1:31 So we just showed headings, we showed in line character styling, we showed paragraphs, let's say I wanted to do.
1:36 And inline for example, code I'll paste a little snippet and you see that the back ticks put the code tag and then a colon followed by a blank line
1:49 And indentation puts a pre tag. When I say, if you see the rendered output in HTML.
1:57 Markdown has indentation which you can use with a sequence of greater than and multiple greater
2:03 than signs. We can see in the preview that I got a first level of indentation and then a second level of indentation,
2:10 which you also see when missed renders to the HTML. What do markdown lists look like? I have a bulleted list just by having a dash.
2:22 Could also be other kinds of symbols such as an asterix and then a numbered list It is just a series of numbers.
2:29 They don't actually have to be in ascending order. I could put them all as one and it would work.
2:35 I see in my preview and the editor and also in my pre in my rendering thanks to MyST rendering into HTML.
2:45 That I get ordered lists and numbered lists from HTML. How about links to URL's.
2:50 This is a place where markdown really excels relative to restructure text I'll paste a little snippet and this is going to have a link to the
2:58 Python homepage. You can see the URL. There, the URL. Is in parenthesis and the link text is in square brackets and when I look at
3:11 the preview and my editor I see the link text and the fact that it's an actual link that I could click on when I save and Sphinx renders via MyST.
3:21 I see that I have a paragraph with link text. I hover over it and that's the link. URL. I don't have to link just to
3:30 URL's out on the web. I can link to other resources on my in my Sphinx site. For example, if I want to link to the homepage from this
3:41 about us, I can do a path to it. I could leave off the ./ and when I save it will re render thanks
3:50 to MyST. I can also see in my editors preview and as I mouse over here I see that's going to point to 'index.html'.
3:59 This starts to bring up some of the coolness of MyST. Combined with Sphinx. The Sphinx knows all the pages on the site and knows the
4:08 title of all the pages in the site. If you want this link text to just use the title of the site and update
4:15 Whenever the title changes, you can just leave empty link text. Now, my tool doesn't know about Sphinx.
4:23 So it just removed the link text but over in the rendered site with MyST and Markdown, it supplied link text from the title of the thing I like to.