Markdown Showdown - All I Know About Markdown
Here it is kids! All I know about Markdown. First! The standard preamble…
Before that though! Some of the possible titles I came up with before writing this:
- Uptown with Markdown
- Downtown with Markdown
- Splashdown with Markdown
- Don’t frown with Markdown
- Get the Markdown Crown
Sorry, anyways! Onwards!!
As a developer, a developer of web, and someone that writes a lot in my digital garden I use Markdown on a daily basis, but what is Markdown?
Introduction: What’s Markdown then?
Essentially Markdown is a way to format your text, like you would in Microsoft Word but without using the toolbar to select the format for the text.
The goal for Markdown is to enable easy to write and easy to read plain text format that can be converted to HTML in the browser.
There are a many differing flavours of Markdown which you may have come across before on the web, places like Discord, GitHub, Jira, Reddit, StackExchange, and even WhatsApp and Facebook all use some form of Markdown!
If you’re interested you can take a look at the original spec from John Gruber posted in December 2004 on Daring Fireball
I’ll be focusing on GitHub Flavoured Markdown Specification (GFM) in this guide.
Like I mentioned earlier Markdown is converted into valid HTML and if you have not encountered Markdown before it before looks something like this in your text editor:
## This is a h2 heading
The equivalent in HTML will be:
<h2>This is a h2 heading</h2>
Which will be converted to a h2 as you see in the web browser. Take a look at this interactive component here 👇 try editing the text on the left:
This is a h2 heading
There are many places to use Markdown as I mentioned earlier, for the examples here I’ll be using the interactive component, if you want to follow along I’ll be using VS Code and Prettier.
There’s also Markdown Forge by Justin Juno which is a very handy tool for writing Markdown in the browser.
Paragraphs and Text Decoration
The basics of Markdown is writing text in paragraphs the whole idea is that it’s readable in plain text before it get parsed out to HTML.
This is a paragraph
One little gotcha here is that there needs to be a clear space between paragraphs otherwise Markdown parses them all as one paragraph as Markdown needs a line between them to identify them as paragraph elements, example:
This is a paragraph. This is also a paragraph.
Adding a clear line space between paragraphs allows Markdown to make the distinction:
This is a paragraph.
This is also a paragraph.
Bold text is achieved by adding double asterisks around the word or paragraph you want to bold.
This is bold.
Italic or emphasis is done by adding underscores around the word or paragraph you want to add emphasis to.
This is italic.
One thing to note in Markdown is that one set of either underscores
or asterisks will make it italic and two sets of either
underscores or asterisks will make it bold, so both
_italic_ will do the same thing as will
Luckily for me as a Prettier user this that decision taken away from
me and will format bold with asterisks (
**bold**) and italic
with underscores (
The thing to remember with strikethrough is that it’s double tilde not a single one, using a single tilde with show the tilde either side of the word/paragraph.
This is not
There are two ways to do headings in Markdown, the first way which you
may see but is way less popular is with
This approach will only give you the option of a h1 and a h2 however,
so the next approach (and what you will see a lot more than the
previous example) is to use hashes
# for going from h1 (single
all the way to h6 (six
With this way of doing Markdown headings if you put these in a
README.md on GitHub it will automatically add IDs to the heading.
This means you can reference the headings in a table of contents when there is a particularly large amount of text in the document.
To add a link to Markdown, be it external (to another site) or locally (to a specific heading) there’s a few ways to do it.
For a raw link you want displayed you can add it as is, or surround it with angle brackets.
Raw link: https://scottspence.com/garden
With angle brackets: https://scottspence.com/garden
To link text wrap the text you want to link in square brackets with parenthesis at the end with the link in there:
There is also the option to add a title to the link where hovering the link will show the title, do this by adding the title in quotes after the hyperlink.
This way of adding links can become a bit disorienting if there are many links in a document making it hard to read and the whole point of Markdown is to make the text easier to read.
The approach I like to take is using keys or references:
<!-- This isn't great to read --> Check out my [digital garden](https://scottspence.com/garden) for more content.
<!-- This is nicer --> Check out my [digital garden] for more content. <!-- Links --> : https://scottspence.com/garden 'add a title here'
<!-- This is nicer still --> Check out my [digital garden] for more content. <!-- Links --> [digital garden]: https://scottspence.com/garden 'title here'
The several examples there are all valid ways to add links, also
notice that I have added HTML comments (
<!-- -->) here, these aren’t
rendered with the Markdown which makes it handy for identifying types
Local link references
Like I mentioned with the headings these can also be linked to headings in the Markdown document, so to skip to the Markdown Images section I’d create a link like this:
Notice that the ID matches the ID added to the heading by the Markdown parser in the HTML, you may need to check this if you have special characters in the heading, in most cases apostrophes and ampersands will be stripped out of the generated ID.
As an example if the heading was Markdown & Images the heading would have the ampersand removed and look like this:
[Markdown & Images](#markdown--images)
Images in Markdown are pretty much the same as links with a subtle
difference, to add an image in Markdown use
!() bang (
indicates it’s an image, square brackets (
) are for the alternate
text that shows up for screen readers and search engines and the
()) are where the link to the image goes, you can also
add in a tool tip (title) in the same way as with links.
With images being a lot like links in Markdown the same applies for using keys and references here:
<!-- This isn't great to read --> ![alt name for image](https://picsum.photos/200/100 'tool tip to show on hover of image')
<!-- This is nicer --> ![alt name for image] <!-- Links --> : https://picsum.photos/200/100 'tool tip'
<!-- This is nicer still --> ![alt name for image] <!-- Links --> [alt name for image]: https://picsum.photos/200/100 'tool tip'
Markdown lists are the same as with HTML, with unordered and ordered lists. Also like with headings, text decorations and bold and italic in Markdown there’s several ways to make unordered lists in Markdown:
There’s several options which can be mixed and matched depending on
how the list is structured and they can all be used in one list, the
identifiers are asterisks (
*), hyphens (
-) and plus (
- Using asterisks
- Using hyphens
- Using plus
Again Prettier has taken away the decision making for me here and decided that hyphens are the way to do this for me in my text editor.
Ordered lists can use a numbering scheme but it’s a lot more
straightforward to use
1. for all the list items when creating
Why? Because if there’s another item that needs inserting in the middle of the list all the numbering has to change.
1. approach Markdown does all the numbering for you:
- Ordered Lists
- All use
- The same number, 1.
Indenting the list items will start a nested list, this can be done indefinitely and the formatting of the bullets will be taken care of by the Markdown parser.
Nesting lists with a lot of content can get a but funky and it’s nice to have content on more than one line.
To get around this there needs to be a clear line in between the bullet paragraph and the additional content to go in there:
1. List item one 1. Indented item that needs additional information More content here, which will be indented with the bullet. ![alt name for image](https://picsum.photos/200/100 'tool tip to show on hover of image') 1. Rest of the ordered list items
To add a check box to a list use the list notation (
-) with square
brackets with either a space between the spaces to indicate an empty
[ ]) or with an x to indicate that it’s checked (
- [ ] Check, check one - [x] Check two
The checkbox needs to start with the hyphen, space then the square brackets indicating if it is checked or not:
- Check, check one
- Check two
Because Markdown is converted to HTML for any markup that is not covered by Markdown’s syntax, there is the option to use HTML itself.
In the case of needing several paragraphs close together there’s the
option to add in a
Line one<br/> Line two<br/> Line three<br/>
Will render the following:
There’s several ways to do a horizontal rule in Markdown, with hyphens, asterisks and underscores.
Like with the text decorations for bold and italic Prettier has declared that hyphens are the way to do this for me in my text editor but I’m detailing the differences here.
Take note of the clear line between the content and the hyphens, if there is no clear break between the two then that will render a h1.
This is regularly used when reply quoting someone on a forum or a GitHub issue.
> to the beginning of the text with a space to create a
The same Markdown formatting applies to the text within it but there may be limitations on with the Markdown parser being used.
Block Quotes Are Cool!
There are a couple of ways to add code snippets in markdown, the first
is inline with single backticks (
`) wrapping the code, the other
is with fenced code blocks.
An inline code
`<h1>Hello world!</h1>` adding the backticks will
usually change the font to monospace with some highlighting to
differentiate it from the rest of the content.
An example of the above sentence here:
An inline code `<h1>Hello world!</h1>` adding the backticks will
Code blocks in Markdown, depending on the parser being used, will often recognise the language and apply some syntax highlighting.
The code fence helps the parser identify the language being used, a code fence will start with three backticks then have the language that’s being used, in this example JS:
GitHub uses Linguist to determine the syntax highlighting on issues and READMEs, there’s a lot in there!
Code fences don’t have to have a language attached to them and a code fence with no language assigned will look like this:
Markdown tables look fugly! There I said it! If there’s content that needs to go into a table, each one of the columns needs to be surrounded by a pipe, like so:
|col 1|col 2|col3|
Then each of the column rows needs to have pipes around the content too.
|col 1|col 2|col3| |col 1 row 1|col 2 row 1|col 3 row 1|
Then for Markdown to know it’s a table there needs to be a row of hyphens surrounded by pipes again, there’s some special notation on the pipes for alignment in the table, here’s what the second row looks like to have all text left aligned:
| :------- | :------ | :------ |
To have all columns right aligned:
| -------: | ------: | ------: |
To have all columns centred:
| :-------: | :------: | :------: |
Notice the colons (
:), they’re how to show which alignment is used
in the table, colon on the left (
| :--- |), left aligned, colon on
the right (
| ---: |), right aligned, colon either side
| :---: |
centred, here’s an example table:
|col 1||col 2||col3|
|col 1 row 1||col 2 row 1||col 3 row 1|
|col 1 row 2||col 2 row 2||col 3 row 2|
The amount of hyphens doesn’t matter, as long as there is at least one. This is where having a formatting tool like Prettier step in to do the formatting for you is super handy.
If there is more content added to the table and the corresponding columns aren’t formatted to fit it could get a bit tricky to read:
| col 1 | col 2 | col3 | | :------------------ | :---------: | ------------------: | | col 1 row 1 content | col 2 row 1 | col 3 row 1 | | col 1 row 2 | col 2 row 2 | col 3 row 2 content |
Year to date analytics for this post