I love writing in Markdown. Most of the time, knowing the basics is enough – structuring content with hashtag #, linking to websites, embedding images.
But then there are the edge cases, and the googling begins (and before you know it, a few hours have vanished…).
In this little ever-evolving list, I collect my finds so I don’t have to search every time.
Now, it depends on which Markdown flavour you’re using. So fair warning: not everything here will work everywhere (I’ve noted where things didn’t work for me).
This list is a living document and I’d love to hear your tips too. Get in touch.
ASCII Art with Markdown
____ _ _ _
| _ \(_) ___ | |__ ___ ___| |_ ___ _ __
| | | | |/ _ \ | '_ \ / _ \/ __| __/ _ \ '_ \
| |_| | | __/ | |_) | __/\__ \ || __/ | | |
|____/|_|\___| |_.__/ \___||___/\__\___|_| |_|
__ __ _ _ _ _
| \/ | __ _ _ __| | ____| | _____ ___ __ | |__ __ _ ___| | _____
| |\/| |/ _` | '__| |/ / _` |/ _ \ \ /\ / / '_ \ | '_ \ / _` |/ __| |/ / __|
| | | | (_| | | | < (_| | (_) \ V V /| | | | | | | | (_| | (__| <\__ \
|_| |_|\__,_|_| |_|\_\__,_|\___/ \_/\_/ |_| |_| |_| |_|\__,_|\___|_|\_\___/
_ _ _
/ \ / \ / \
( v | o | n )
\_/ \_/ \_/
_ _ _ _ _ _ _ _ _ _ _ _ _
/ \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \
( R | e | i | n | e | r ) ( G | ä | r | t | n | e | r )
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
Okay, I don’t use this all the time, but because ASCII art is always fun to look at, it gets top billing. I made the one above with this ASCII generator. Markdown doesn’t cope well when you just dump text art straight into a document. But you can trick Markdown by adding 4 spaces before each line….
Images
Centering Images
Sometimes I want to display images centred. Like this:
And a tagline, also centred
What you can’t see here in Git is that the image is centred. Yeah, it’s HTML and a bit of a hack. But who cares – it works.
For Marked App I need to use the SVG format for the logo. Otherwise the PDF export won’t work:
Here’s how:
<p align="center">
<img src="https://www.reinergaertner.de/austausch/b2bSOME_4c_250-WHAxlQ0LNg/b2bSOME_4c_250.svg" width="200" height="124"/>
</p>
Links
Links Within the Same Page
Sometimes I want to link to a section on the same page. This works (unfortunately not here, but on GitHub and similar platforms) like so:
Link to the section “Multiline Blockquotes”
Watch out – this only works if:
- Section headings with multiple words are connected with hyphens
- The link target must be lowercase (that’s why it took me forever to get it right)
Like this:
[Link to the section "Multiline Blockquotes"](#displaying-multiline-blockquotes)
Linking External Images
Essentially this works the same as URL links, except you add a “!” before the square bracket:
It gets a bit more fiddly with nested links:
[](https://example.com)
Blockquotes
Displaying Multiline Blockquotes
With blockquotes, you need to add an extra line break. In this example, it didn’t work:
First line Second line
The markdown looks fine, doesn’t it?
> First line
> Second line
This is how it looks the way you’d want it:
First line
Second line
The difference is the blank line in between:
> First line
> Second line
Creating a Nested Blockquote
Sometimes you want to add a reply to a blockquote. Useful for responding to an existing comment. Here’s how:
A first comment
And here’s my two cents
So in the “code” it looks like this:
> A first comment
>> And here's my two cents
Lists
Creating Tidy Lists
This is how you make well-structured lists. The “continued here” item is indented with a TAB, and it lines up properly:
a paragraph
continued here
another paragraph
and another
further paragraph
1. a paragraph
continued here
2. another paragraph
3. and another
further paragraph
Task Lists
In some places you can also include task lists. You can mark completed tasks with an “x” inside the square brackets.
[ ] Mercury
[x] Venus
[x] Earth (Orbit/Moon)
[x] Mars
[ ] Jupiter
[ ] Saturn
Unfortunately this doesn’t work everywhere. Unicode might help – see also:
⍻ NOT CHECK MARK
☑ BALLOT BOX WITH CHECK
✅ WHITE HEAVY CHECK MARK
✓ CHECK MARK
✔ HEAVY CHECK MARK
🗸 LIGHT CHECK MARK
🗹 BALLOT BOX WITH BOLD CHECK
◯ LARGE CIRCLE
⭕ HEAVY LARGE CIRCLE
⍻ NOT CHECK MARK
☑ BALLOT BOX WITH CHECK
✅ WHITE HEAVY CHECK MARK
✓ CHECK MARK
✔ HEAVY CHECK MARK
🗸 LIGHT CHECK MARK
🗹 BALLOT BOX WITH BOLD CHECK
◯ LARGE CIRCLE
⭕ HEAVY LARGE CIRCLE
Markdown Special Characters
Emojis in Markdown
I’m not really an emoji person. But since it’s so hard to add colour to text, emojis can come in handy. It’s dead simple:
Red apple (🍎)
Red apple (🍎)
A good overview of emojis including shortcodes can be found here: Emoji Unicode Tables
The overview also shows that the same emoji will look different across platforms.
Unfortunately the input in Markdown isn’t particularly intuitive – for example:
The code for the “airplane” emoji is “U+2708” according to the emoji table. To get it to display (✈), you need to change it like this:
- Remove the “U+” and replace it with “&#x”. Then add a semicolon at the end.
from "U+2708" you get ✈
You just need to know that once.
Not everywhere, but on GitHub it works when you put the emoji name from the list above between colons:
:honeybee:
:honeybee:
Displaying Markdown Formatting Characters
Sometimes you want to display special characters that Markdown uses. You can do this with a backslash: \
a test
* a test *
The asterisks are displayed like this:
\* a test \*
Markdown Highlighting
Emphasising Really Important Bits
Obviously you can use bold. But sometimes I want to emphasise something even more within the bold text, maybe in italics. So I need something bold and italic:
This text is very important.
**This text is _very_ important.**
Strikethrough Text
This is actually quite simple with two leading tildes: strikethrough!
This is actually quite simple with two leading tildes: ~~strikethrough~~!
Markdown and Colours
This depends a bit on which Markdown flavour you’re using.
In my CMS (Grav CMS) it doesn’t work, but on Gitpitch I can change the text colour like this:
Some Markdown text with <span style="color:#fffffff">some *white* text</span>.
On GitHub and similar platforms, unfortunately that doesn’t work. To highlight something in colour, you could use “diff”. But it’s not particularly elegant – the “-” and “+” remain, of course.
+ this text is highlighted in green
- this text is highlighted in red
Unfortunately this doesn’t work on GitHub and similar platforms (but it does in my Markdown CMS) – so give it a try:
Text in red
<font color=red>Text in red</font>
and then there’s also the yellow highlighter!
and then there's also the <span style="background-color:#FFFF00">yellow highlighter!</span>
Markdown Structure
Displaying Text in Boxes
This works on GitHub and similar platforms, and also in my Grav CMS:
| Text in a box |
<table><tr><td>Text in a box</td></tr></table>
Collapsible Sections in Markdown
A handy way to structure text further, especially when you want to keep the page tidy. The only downside is the box looks a bit odd when you click the arrow:
Click here to read more
This can be any text, and it can even contain **markdown** formatting.In Markdown it looks like this:
<details>
<summary>Click here to read more</summary>
This can be any text, and it can even contain **markdown** formatting.
</details>
Markdown and Tables
This is a topic all on its own. I’ll write more about it at some point. For now:
- Tables can be created nicely with the “Markdown Tablemaker”. Downside: it’s generated on the server and not saved locally.
- The best Markdown editor I know that handles tables brilliantly is Typora (was free at the time of writing).
- If you work with tables a lot, check out Tableflip. Doesn’t cost much (19 Euro) and does what it’s supposed to.
- If you use Google Sheets and Chrome, definitely look at the extension “Markdown Tablemaker”. It lets you create Markdown tables from any Google Sheet. My favourite for larger tables that need sorting first (which is more fiddly in the Tableflip app).
From the archives of reinergaertner.de, running since 1997. Translated with AI help and my questionable bilingual proofreading. If you spot a Germanismus – that’s a feature, not a bug.