Writing in Markdown

Summary

In this video, I walk you through Markdown basics, perfect for those new to our programming course. I explain how Markdown is a lightweight markup language that uses simple symbols for formatting text. I demonstrate key syntax including headers with hashtags, bold text with asterisks, and creating both bullet and numbered lists with dashes and numbers. I show how to format links, quotes, code blocks (both inline and multi-line), tables, and images. I emphasize that Markdown is the industry standard for technical documentation, works with any text editor, and integrates well with version control like Git.

Transcript

Since you're watching our course on programming, you've probably already heard of Markdown. But on the off chance that you haven't, I'm just going to walk you through some basic examples of the syntax and some of the pros of using Markdown to write technical documentation. If you feel comfortable with Markdown, please feel free to skip ahead to the next video. So Markdown is a lightweight markup language that lets you write formatted text using some simple and easy to read symbols. For example, if you want to make something bold, you can wrap that section or that word in double parentheses, or you can use hashtag to make headings. Basically, it's a very simple way of writing content and it works in any text editor. You don't need any specialized software. And since it's plain text, it's also a very good fit for version control like Git. So if you jump here, we can see some of the benefits I already mentioned, right? It's lightweight. It's very portable. You can convert it to many formats, so to HTML, like what we are going to be doing, but also to PDFs or a lot of other formats that you might need. It's simple and easy to read. Yeah, it's just a file, so it's very easy to chuck into version control, which is going to be very beneficial if you are working with multiple versions of your blog post, right? You can kind of keep track of it. No need for specialized software. You can just plop it into whatever you want and it's going to be good to go. So this is some of the benefits of Markdown and once you get used to it, it's really, really nice and simple to work with. Also worth mentioning here is that this is most often the industry choice. So if you're going to be working professionally with software and you're going to be doing any form of documentation, either technical on GitHub or whatever, right? Readme files. You've probably seen the readme files for the repository that follows this course. It's also a Markdown file, so it's really worthwhile to learn. It takes five minutes to learn and then you're in it and then you will get used to writing using this syntax. So if you have a plan of going into professional software, it makes a lot of sense to get really, really familiar with Markdown. So let's just quickly run through some syntax examples here and this is how you do headers. It's literally just a hashtag, one, two, and three hashtags, depending on the level of header you want. I typically only use one, two, and three, but you also have four, five, six, however many you need. And yeah, it's just hashtags and then you will get it and how we're going to be doing, how we're going to be parsing, it will matter which level you're using. So you'd have bigger for one, two, and three, maybe as you have seen in something like Word. It's the same concept here. And again, make something bold. We already talked about this, like wrap something in double asterisks and then you can make it bold. Lists, also very commonly used. You just create them using a dash and then a space. And if you want some hierarchy, you can add on the new line, two more spaces and another dash, so you get the hierarchy, right? The numbered list, you do the same. You just do the numbers, one, two, three, four, five, however many. And then you can also, with another pair of spaces, make a hierarchy in the list. Very straightforward. And Markdown will like literally show them as you see here, right? So this one belongs to the second item, right? Links and quotes. So the way you create a link is square brackets and then parentheses for the actual link. Right now, this is not rendered as how you would see it, but if you have seen like a blog post on one, like one of my blogs, you will see only this piece of text right here, maybe with some formatting. And then if you click it, you will go to example.com. The same thing here. Also, if you want to do quotes, you do like this little symbol right here that I don't know the English word for, for each line. And then you get this little quote here. And this will also be converted into, in our case, it will be converted into some HTML elements, so you can also format how this quote looks. I believe the HTML element is literally just called the, it's called blog quote. So you can also style it if you need to. Code blocks. You can either have inline code with a, like you wrap them in a single pair of backticks or if you want to, and I want to show like more complete code examples, you will do free backticks, the name of the programming language, in this case here, Go. Put in the code and then finish off the block with another pair of, sorry, another set of backticks, free like you did in the beginning. And you can actually run this backtick. And then you can also create a new block. And you can actually run this piece of code right here. So, so this is how we do, do code blocks. Either do inline, or if you want to have the language also, we can, we can do the free backticks, the name, and then the code, and then finish off with another set of free backticks. Tables, syntax, also very straightforward. You do colon dashes or three dashes for the outer sections. And in the middle section, you will do like colon, three dashes and colon again. And you get basically what you see right here. And finally, if you were to do images, you will do like you do a link, but you would just append or prefix it or gets it called with an exclamation mark. So still square brackets, the name, and then the, the source, which is going to be, for example, as you see right here, the path to the image in parentheses, and then exclamation mark in front of all of that. And then you have also images to your, to your markdown documentation. So that's basically it. I know I went through this very, very fast, but you can always look it up or refer to this video or this presentation if you want to. It's a standardized format, so you can always find tons of different examples of how you do things in markdown and do like one article, and you will be, be very familiar with the syntax and how it works. And you will feel like just any other text processing format, right? But enough of that, let's, let's get into the code and actually start having some markdown articles being rendered on our blog.