Using Markdown
This Quick Reference focusses on Markdown, the content creation and formatting language used in Hugo. For a more lengthy tutorial, have a look at the excellent Markdown Tutorial and the official Cheat Sheet, which served as inspiration for this page.
Check also the Mainroad theme page for the implementation and specific behaviour of the different Markdown commands in the Mainroad theme. Not all modifiers work as one would expect them to do.
Here we go:
Headers
# H1
## H2
### H3
#### H4
##### H5
###### H6
Emphasis
*italics* or _italics_
**bold** or __bold__
~~strikthrough~~
Lists
1. ordered list item
1. second item in list (no need to put the right number, just a numeric value)
* unordered list item
+ second item in unordered list
- third item in unordered list
Indent by using spaces (space marked here with a .):
1. first item
..* first subitem
..* second subitem
1. second item
Indent can be used without lists!
Links
Anchors are marked with angle brackets: [link text]. Link can be added behind the text: [link text](link), where the link can be an absolute or relative reference.
To keep optimal readability, use a [link reference][1] which can be a number or any string.
[1]: https://www.google.com/
Images
These use a similar syntax to links but with an exclamation mark; the text between the angle brackets pops up when hovering or when the broswer doesn't display images (depends on theme).
![me][1]
[1]: /img/me-caricature.png
Note it is not possible to manipulate size and position of the image.
Code and Syntax Highlighting
Use single opening and closing back-ticks (`) for code formatting inline and 3 back-ticks before & after to force blocks of code. Some themes and renderers support syntax highlighting, add the language behind the first 3 back-ticks.
Tables
Tables are not part of the Markdown spec, but there is support for them. Note that the theme can influence the layout of the headers based on the left/center/right formatters.
|header|header|header|
|:-----|:----:|-----:|
|left |center|right |
Blockquotes
> this is a blockquoted text
> long text: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis eu dui enim.
> Fusce ac accumsan quam, ...
Inline HTML
Just use HTML code in the content. Handy for external embedding. Mixing markdown with HTML doesn’t work very well.
<p align="justify">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis eu dui enim. Fusce ac accumsan quam, in iaculis ex. Aenean eleifend est at dolor ultricies fermentum. Morbi tincidunt volutpat libero ac malesuada. Ut vitae porta elit, id placerat orci. Aenean sollicitudin justo at dui auctor, nec tempor turpis hendrerit. Nullam vel tellus quam. Vivamus aliquam nisi in egestas rhoncus. In hac habitasse platea dictumst. Nam malesuada blandit erat, eu pharetra odio scelerisque sit amet. Sed tempor nisi non tincidunt eleifend.
</p>
Horizontal Rule
Three or more hyphens (-), asterisks (*) or underscores (_).
---
***
___
Line Breaks
Line breaks are a bit odd in Markdown and depend on the renderer and the theme used. It’s advisable to experiment with the theme to figure out how it exactly reacts. The following syntax should be true in any theme or renderer.
Two newlines should give a new paragraph.
Different lines
with no
punctuation marks
forces everything to a single line.
Adding two or more spaces at the end of a sentence simply adds a sinlge break.
