Markdown

[00:00:00]
>> Mike North: The next thing we're gonna talk about is building great documents in Visual Studio Code. One of the great strengths of the way markdown is handled in Visual Studio Code is it matches really nicely with the way GitHub handles markdown. So what I'm gonna show you here, this is sort of a cheat sheet for all of the different things you can do in the body of a GitHub issue that you would create.

[00:00:26]
Or pull request that you'd open or just markdown files that you would check into your project. So, the first thing I wanna show you or just gonna go and look at the same project on GitHub. Oops, sorry it's over here. So when we just look at a folder like docs/here.

[00:00:47]
Here are the files in this folder. If you have a readme markdown file below, that will be shown below. So think of it as almost like the same way like if index.html will be shown if you want to view a set of like static web assets. And you just go to a particular folder path.

[00:01:06]
That is sort of the implied thing that you end up looking at. And so even as we drill through this, like we can see that there are other README's inside each of these folders. So it's kind of nice to leave, especially if you have a large team and you have certain conventions that apply within a particular area of your code.

[00:01:27]
Just create a readme within that folder structure. It doesn't just have to be the one read e for the whole project. But this can serve as a good living document that is versioned along with your code. If these practices change over time it's really easy to look at the history, just like you would with code, and to see how this has evolved.

[00:01:50]
So we're gonna look at all of these different markdown tricks that you can use. The way you create images with markdown is pretty simple. You begin with an exclamation mark, and then within square brackets you have the name of this image. And that's used to populate the alt attribute of the image tag that we're seeing rendered below.

[00:02:14]
And then you can have a path to a file here, that can be a relative path. So this one happens to be checked into this project. It doesn't have to be something that's hosted in the CDN somewhere, it's just, it is another file and we can refer to it that way.

[00:02:28]
So, here is the way that ends up looking, just so you can understand the size of it, it's about the full height of my editor here. So that's great but it's kind of limiting because we have to size our images just right. So if we wanted to deviate from that and customize things a little bit.

[00:02:50]
Turns out you can also use an image tag as well. And this gives us the ability to use almost all of the attributes available on image tags. You can't use things like source sets, which are typically for handling a retina version of an image, an irregular version of an image.

[00:03:07]
That's a little bit too involved and complicated. But we can specify a height. There's an align attribute and think of that almost as it is a float but it does even more things than a float does. And we've got vpace and hspace and think of those as horizontal and vertical margin around this image.

[00:03:27]
So, here's what we end up with with this mark up above. You can see we begin with something that is floated to the right. And just like when we use like a CSS float, it doesn't, when you float something it doesn't really, it ends up having no height, right.

[00:03:46]
So that's what lets us float to the right, and then we can put something to the left. And these end up sort of being horizontally centered on each other. The reason this is not aligned up with the top edge here is because we have got this vspace of 20.

[00:04:00]
So that is what is making it come down like this. When working with GitHub and this is where GitHub and VSCode split a little bit, it likes to wrap everything on a particular line with the paragraph tag. And so you'll see, like if you have a bunch of images, if we wrote this for example, right and sent it up to GitHub.

[00:04:25]
Sorry, if we had a couple images like this, right, without floating them, like one two three, VS code would show them as inline images. Whereas GitHub would wrap each of them in a paragraph tag. The consequence for you is you would see three images, one on each line.

[00:04:42]
On GitHub, whereas here, you would see them next to each other on the same line. But this here, what we're looking at, that works,
>> Mike North: There it is, that works on GitHub as well. Let me just get my zoom right. So there's our little floater to the right thing.

[00:05:05]
>> Mike North: So this align attribute works on a variety of elements, paragraph tags are a common thing to use. Because if you provide one GitHub will not automatically wrap stuff in a paragraph tag for you. So that's what let's us do something like this, where we've got left, right and center.

[00:05:22]
So if you want to sort of, if you looked at the Readme for this project you see we've got a little image centered and at the top. And we've got our build status tags and things centered right below it. This is how we're able to do that. You can do this in a poll request or an issue.

[00:05:39]
Anywhere where you're using markdown syntax this is important.
>> Mike North: So what I'm showing you here is we have align top and bottom. And keep in mind we're dealing with sort of a single like horizontal line of content here. But what we can do is use the top and bottom align to take these two images to the left and float one like vertically align one up and vertically align the other down.

[00:06:08]
So the only way we're allowed to see this is cuz we have a larger image that sort of defines the height of this paragraph tag, if you will. And that gives us the ability to take smaller things and choose where we would like to align them.
>> Mike North: Hopefully we've all used unordered lists before, this is one the one of the first things you'll typically learn as you'll start working with MarkDown.

[00:06:32]
So that will end up rendering like this. We have ordered list as well and you will note here so we've got again the pattern is the Mark Up and then how it's rendered is below it. So you;ll note that I have got 111. You could do one, two, three if you really wanted to.

[00:06:51]
However, the benefit here is if we added something into the middle of the list, we would not have to go through and explicitly renumber everything ourselves. It'll take care of incrementing that number as we go along. One of the annoying things about this kind of list is you can't use this syntax up here and get nested ordered lists.

[00:07:16]
We can fall back to regular HTML and do something similar though. But we've got ol for ordered list, list items and then we've got nested ordered list in the side. And we end up getting something that looks kind of like an outline. So this type attribute is what gives us that.

[00:07:33]
If you were making a table of contents or something where you wanted to refer to like section A, subsection one, something like that, this would be a great way to do it.
>> Mike North: So I learned about this preparing for the course, there's something called description lists, I've never actually used this before.

[00:07:52]
But these come in pairs where you've got a description, well, you've had a title and a description. And it'll render itself as sort of the title and then it'll indent the description. I'll show you how this looks on GitHub.
>> Mike North: Basically like that. That is how it ends up being rendered.

[00:08:17]
So kind of nice if you had maybe your contact information. You can have name and then a couple of things below it, without having to deal with bullets or something like that. This is my favorite here. This, you will. You will look like a Mark Down wizard to people if you start doing this in pole requests.

[00:08:42]
So, is there anyone ever reported an issue where you've had to like paste some log output like. Mike, I'm having trouble installing this project, here is the error message I'm seeing and you paste the big thing. And this of course for everyone reading this Issue. They're gonna have to scroll through everyone's log output and like, other people will come comment on it and say no, I get this huge log instead.

[00:09:06]
And someone else will say, no I get this mega log output. And before long it's like eight pages that's a mile long. So we can use detail summary here. What ends up happening is, we get a little collapsed element here, and we can open it up. And you see we were able to use a Markdown inside of it.

[00:09:23]
This is a code block with typescript syntax highlighting, and you see that we can keep that collapsed in here. So this is a nice way to let people sort of optionally open things up, or I've at times used this for quizzes. Where you have the question and then you can open that up and see answer, but the use has to click to open it up.

[00:09:43]
So this stands out because it's a little bit of interactivity in your documents. If you are doing this, keep in mind that in order to transition from the HTML world Into back into the Markdown world here you want to have an empty new line. Otherwise it will be seen as just HTML text that isn't back text.

[00:10:05]
I can show you what that will look like if we go down here. If I were to delete that.
>> Mike North: Yeah, see, that is less impressive there. It's just regarding this as regular text. So just make sure that you have that new line in there and it should work out, just like that.

[00:10:33]
And by the way, the way I'm able to get this little line here like this, that is a block quote. So if we look at the Markdown here that's going on behind the scenes. I'm just using these to basically shift everything in and to give myself a nice little space.

[00:10:51]
So, we can really easily see like this is code and this is the answer. So, detail summary, use it anytime you're pasting a giant like log output and people will open it up if they care and they won't, if they don't. And of course, me for something absolutely amazing.

[00:11:07]
That is summary that's appearing here. And then finally, you can use tables in Markdown and you just have to basically, like this is the Ascii art version of the table. Be careful, because if you get even one row incorrect here, I'll show you what happens.
>> Mike North: It basically, let's see if we can screw it up a different way.

[00:11:36]
Seems more tolerant than I remember. What if we do that?
>> Mike North: I am surprised that it's, it's keeping up here. I would not necessarily trust all. I'll Markdown renderers to handle this gracefully. But you can see these tables sort of basically unravel into the row syntax again. And you just see a bunch of pipes and dashes and stuff and it wouldn't understand that it should create a table tag and table rows and table columns.

[00:12:08]
Wow, more robust than I thought maybe I have to save it. Let's see. Now it actually is handling it. Bravo, code team. So, those are my Markdown tips there. Now, in terms of, if you had to just remember one, remember details summary. Just remember that and if you remember two, align.

[00:12:32]
>> Mike North: So what I suggest you do, one of the benefits of having, these slides as code within this project. Take notes as we go along and commit those notes to yourself as part of these like exercise solutions. So we'll be going through and you can use some of these like tips here to style your notes in some rich way.

[00:12:55]
But just like with the key bindings, as you start to like just incorporate a few things to start, don't try to learn it all at once, it won't stick. It never does. But just pick one or two or three things and try to focus on making use of that thing.

[00:13:12]
And once it becomes internalized, you will know when you've internalized it, you don't have to think about it anymore. And then you can move on to the next one