# Markdown Shenanigans. One fine weekend, while trying to "create my site from scratch", I got tired of HTML and decided to play around with the markdown language. It gave me a much "cleaner" authoring experience, and I had a lot of fun playing around with it. So I decided to share my learnings in the hope that it will help you or at least spark your curiosity. According to our trusty friend, [Wikipedia](https://en.wikipedia.org/wiki/Markdown), "Markdown is a lightweight markup language for creating formatted text using a plain-text editor". Markdown is quite popular with people who spend a lot of time creating technical documentation. Its key selling point is readability without the encumbrance of tags and formatting that you'll get in a language like HTML for example. Here is a summary of the things I learned along the way. For each section, I show a preview of the actual markdown syntax followed by the end result. ### Headings Headings in markdown are created by starting with one or more hash (#) characters. Depending on the heading type, the number of hashes (#) can range between 1 (for H1 or main headings) and 6 (for smaller headings, a.k.a subheadings). The title (markdown shenanigans) is an example of an H1 (#) heading. To view other headings and see the difference between them, check the list below: Markdown Syntax: ```plaintext # Heading 1 (H1) ## Heading 2 (H2) ### Heading 3 (H3) #### Heading 4 (H4) ##### Heading 5 (H5) ###### Heading 6 (H6) ``` Result: # Heading 1 (H1) ## Heading 2 (H2) ### Heading 3 (H3) #### Heading 4 (H4) ##### Heading 5 (H5) ###### Heading 6 (H6) ### Making Emphasis with italics or bold… Emphasizing a word or sentence can be done by adding at least one asterisk (\*) at each end of that word or sentence. ```plaintext *One asterisk at each end italicizes your words.* **Two asterisks at each end make your words bold** ***Three asterisks at each end make your words bold and italicized*** ``` *One asterisk at each end italicizes your words.* **Two asterisks at each end make your words bold** ***Three asterisks at each end make your words bold and italicized*** ### Creating (Block) Quotes To create block quotes, you need to indent each line using a right-angle bracket (>) or what mathematicians would call a "greater than" symbol. Additional angle brackets create inner block quotes. ```plaintext > ***This is a block quote in italics and bold*** >> This is an inner block quote\ I did this just because I can\ and also because I like it >>> I can even try an inner-inner block quote\ That's how we stars do it >>>> Now keep your complaints to yourself :p ``` > ***This is a block quote in italics and bold*** > > > This is an inner block quote > > I did this just because I can > > and also because I like it > > > > > I can even try an inner-inner block quote > > > That's how we stars do it > > > > > > > Now keep your complaints to yourself :p ### Now let us try lists: Creating a random unordered list… ```plaintext * Apples * Oranges * Pears - One - Two - Three + First + Second + Third ``` * Apples * Oranges * Pears * One * Two * Three * First * Second * Third and now a random ordered list… ```plaintext 1. Number one 2. Number two 3) Number three 4) Number four ``` 1. Number one 2. Number two 3. Number three 4. Number four We can also create nested lists like… ```plaintext * Fruits 1. Oranges 2. Pears 3. Apples * Numbers - One - Two - Three ``` * Fruits 1. Oranges 2. Pears 3. Apples * Numbers * One * Two * Three In both cases, we need to indent at least 2 spaces on the next line to create a nested list. Let's see how a link looks like: ```plaintext [My first Blog Post](https://www.isrxl.com/i-came-i-blogged-i-conquered/) [Check out isrxl blog][id] [id]: isrxl.com "title" ``` [My first Blog Post](https://www.isrxl.com/i-came-i-blogged-i-conquered/) [Check out isrxl blog](isrxl.com) [https://isrxl.com](https://isrxl.com) ### Get a picture ```plaintext ![Nice Picture](https://unsplash.com/?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit) ``` ![Nice Picture](https://unsplash.com/?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit align="left") ### How do we write code blocks? This is probably my favourite use of markdown. When I was still trying to create my web pages from scratch, I was having a hard time displaying code snippets in the way most tech professionals would like when reading a tech article. Once I saw how easy it was in markdown, I quickly dumped HTML/CSS/JS (for now at least). Code blocks can be created by indenting the line (pressing the tab key) four (4) times in markdown before writing the code ```plaintext get-AzResourceGroup get-AzContext ``` ```plaintext get-AzResourceGroup get-AzContext ``` Another way to create code blocks is by starting a new line with the backtick character three (3) times and optionally following it with the code language. After this, you can write your line/block of code on a new line. Once you are done you can end the code block by using the backtick character three (3) times on a new (and final) line... Like in the code example below: ````plaintext ```powershell get-service ``` ```` ```powershell get-service ``` You can also write code in markdown as inline code. For example, ```plaintext Inline code: `get-AzContext`, another example is `1 + 5 = 6`. ``` Inline code: `get-AzContext`, another example is `1 + 5 = 6`. ### Closing Remarks Once you get the hang of it, the markdown language makes authoring technical documentation quite easy and enjoyable. To create markdown files, you can simply use a plain text editor like notepad or notepad++. If you like to create markdown files and also enjoy the use of some custom plugins like live visualization, Visual Studio Code should be your go-to tool. If you would also like to play around with markdown, you can check the following sites for good examples: [Getting started with Markdown](https://www.markdownguide.org/getting-started/) [Markdown Tutorial](https://www.markdowntutorial.com/) [CommonMark Website](https://commonmark.org/help/tutorial) Happy "markdowning' or is it Happy "markingdown"? Enjoy.