Markdown is a commonly used markup format used for blogs, documentation, and other longform content. It translates easily into HTML, and is easy for humans to read in its raw form.
We use Markdown heavily at Doctave (since our product supports it), and often found ourselves double-checking syntax. “How did you right-align a table column again?”. So, this is a reminder for our future selves.
In this post, we will go over Markdown’s core features and associated syntax. We will also mention some commonly found extensions to Markdown.
Basic Markdown features
First, let’s go through basic Markdown features supported by all parsers.
You can specify headings in the ATX
format, where the text of the heading is preceded by 1-6
Alternatively, you can use the
where you underline your heading with either
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 // ATX "hash" style # H1 heading ## H2 heading ### H3 heading #### H4 heading ##### H5 heading ###### H6 heading // Setext "underline" style H1 heading ========== H2 heading ----------
You can bold and italicise text by surrounding a string in one or two
_ characters. One character for italics, two for bold.
1 **Bold text**. __This is also bold__.
Bold text. This is also bold.
1 *Italicised text*. _This is also italicised_.
Italicised text. This is also italicised.
Markdown supports unordered and ordered lists.
You can use the
- characters to define unordered lists:
1 2 3 4 5 * Mary * had * A little lamb Its fleece was white as snow
A little lamb
Its fleece was white as snow
⚠️ Note how the last line “Its fleece was white as snow” is interpreted as being part of the list item. As long as your indentation matches the start of the list item, you can include multiple paragraphs inside a list item.
1 2 3 4 1. Mary 2. Had 3. A little 1. Lamb
- A little
I never remember which braces come first with Markdown links…
1 Here is a link to [Doctave](https://doctave.com).
Here is a link to Doctave.
Images work like links, except you put an exclamation mark before the link text.
1 ![A random image](https://picsum.photos/600/400)
1 > It's true, because it's a quote
It’s true, because it’s a quote
Markdown supports inline code as well as code blocks. You’ve seen plenty of examples already in this document.
1 Use `backticks for inline code snippets`.
backticks for inline code snippets.
Either use three backticks
1 2 3 ``` For().your().code() ```
Or indent your code with 4 spaces:
For the same effect:
Some providers will support syntax highlighting, in which case you can specify the language of the code example:
1 2 3 4 5 ```ruby def hello puts "world" end ```
Isn’t it pretty?
1 2 3 def hello puts "world" end
If you prefer, or your code example contains 3 backticks, you can replace
backticks with the
1 2 3 ~~~ Not with backticks ~~~
1 Not with backticks
You can include inline HTML in your Markdown document. Note that some services will disable this feature for security reasons.
1 <p style="transform: rotate(12deg); transform-origin: bottom left;">Askew</p>
It’s best to check your Markdown library’s support for these features.
1 The following should be ~~redacted~~
The following should be
1 2 3 - [ ] This is a list of to-dos - [x] This is a completed item - [ ] This is an uncompleted item
- This is a list of to-dos
- This is a completed item
- This is an uncompleted item
Tables can be annoying to write by hand. However there are tools you can use that do the formatting for you.
Note in this example how the first row becomes the table heading. Also, the
second and third columns are center and right-aligned respectively. This is
achieved by using
: characters in the divider as shown below.
1 2 3 4 | This is a heading | Centered | This is right-aligned | |--------------------------------|:--------:|-------------------------:| | This is content for a columns | Hello | This is **bold** | | You can have more rows | World | And more columns |
|This is a heading||Centered||This is right-aligned|
|This is content for a columns||Hello||This is bold|
|You can have more rows||World||And more columns|
Doctave makes docs-as-code a breeze
Tired of wrangling open source tools and complex documentation deployments? Doctave makes deploying documentation sites with docs as code easier than ever.
Start a free trial today!
Articles about documentation, technical writing, and Doctave into your inbox every month.