This article started life as a cheatsheet for me as I was was trying to work out how my new website using Hugo - a framework for building websites, actually works:
- How to write a document in Markdown which would cover everything I need (this article more than truly covers all the elements I would ever use).
- Create a sample document with everything in it so that I could check that all of my styles worked properly.
- Check that my custom shortcodes to hadndle responsive images, video and 360 panos work.
The way I have written this article is to show the rendered text first such as this which will then be followed by the Markdown syntax in this colour.
Headings
You can also use underlines for headings but I find the use of hashes easier so I’m sticking with them.
H1 Heading
# H1 Heading
H2 Heading
## H2 Heading
H3 Heading with emphasis
### H3 Heading with **emphasis**
H4 Heading
#### H4 Heading
Paragraphs
Here’s a line for us to start with.
This line is separated from the one above by two newlines, so it will be a separate paragraph.
This line is also a separate paragraph, but…
This line is only separated by a single newline followed by two spaces at the end to create a hard break, so it’s a separate line in the same paragraph.
This line is also a separate paragraph, but...__
This line is only separated by a single newline followed by two spaces at the end to create a hard break, so it's a separate line in the *same paragraph*.
Inline Formatting
This text is italicized with underscores, and this is italicized with asterisks.
This text is _italicized with underscores_, and this is *italicized with asterisks*.
This is strong emphasis and with underscores.
This is **strong emphasis** and __with underscores__.
This is italicized strong emphasis and with underscores but best practice is asterisks only.
This is ***strong emphasis*** and ___with underscores___ but best practice is asterisks only.
This is deleted text.
This ~~is deleted text.~~
Blockquotes
To create a blockquote add a > in front of a paragraph
Blockquotes are useful for highlighting something in an article
Note that you can use Markdown syntax within a blockquote and remember to add an extra > if you need a line break.
And this is a nested blockquote!
> Blockquotes are useful for highlighting something in an article
>
> **Note** that you can use *Markdown syntax* within a blockquote and remember to add an extra > if you need a line break.
>
>> And this is a nested blockquote!
Footnotes
This footnote will appear at the end of the article1
Footnotes can also be named however you like 2 but the naming will be ignored and the next number in sequence will be shown instead.
This footnote will appear at the end of the article[^1]
Footnotes can also be named however you like [^iamafish] but the naming will be ignored and the next number in sequence will be shown instead.
[^1]: This is the footnote that will appear at the end
[^iamafish]: Cod actually
Tables
Tables rendered in Hugo are pretty crap. There’s basically no easy way to format them without using global CSS styles for the table elements.
Italic default | Bold default | Strikethrough default | Code default |
---|---|---|---|
italics | bold | code | |
italics | bold | code | |
italics | bold | code |
| Italic default | Bold default | Strikethrough default | Code default |
|----------------|--------------|-----------------------|--------------|
| *italics* |**bold** |~~strikethrough~~ |`code` |
| *italics* |**bold** |~~strikethrough~~ |`code` |
| *italics* |**bold** |~~strikethrough~~ |`code` |
Italics left | Centred Bold | Strikethrough default | Code right |
---|---|---|---|
italics | centred bold | this is code | |
italics | bold | code | |
italics | bold | code |
| Italics left | Centred Bold | Strikethrough default | Code right |
|:------- | :-----: |-----------------------|--------: |
| *italics* |**centred bold**|~~strikethrough~~ |`this is code` |
| *italics* |**bold** |~~strikethrough~~ |`code` |
| *italics* |**bold** |~~strikethrough~~ |`code` |
Code Blocks
Code block with backticks
Use 3x backticks at the start and end of the code block.
html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>
Code block indented with four spaces
Or indent it with 4x spaces
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>
Code block with Hugo’s internal highlight shortcode
Use Hugo’s highlight shortcode to highlight code, for example with html: {{< highlight html >}} a bunch of html code {{< /highlight>}}
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>
List Types
Ordered List
This is the first list:
- First item
- Second item
- Third item
- Indented first item
- Indented second item
- Fourth item
This is the second list:
- Another first item - note that list numbering is taken from the first element (13)
- Another second item - subsequent list numbers are ignored (24)
- Another third item - and will be automatically incremented
This is the first list:
1. First item
2. Second item
3. Third item
1. Indented first item
2. Indented second item
4. Fourth item
This is the second list:
1. Another first item which will continue from the previous list
2. Another second item - subsequent list numbers are ignored (24)
3. Another third item - and will be automatically incremented
Unordered List
- List item using +
- Another item using -
- And another item using * however just stick to the same symbol
+ List item using +
- Another item using -
* And another item using * however just stick to the same symbol
Nested list
- Item
- First Sub-item indented
- Second Sub-item indented
- Item
- First Sub-item indented
- Second Sub-item indented
Mixed list type
- Unordered Item
- First Sub-item indented
- Second Sub-item indented
- Another unordered item
- Unordered Item
1. First Sub-item indented
2. Second Sub-item indented
- Another unordered item
Task list
- an unchecked task list item
- checked item
- [ ] an unchecked task list item
- [x] checked item
Definition List
Make sure there are 3x spaces between the : and the definition and 4x spaces for additional lines
- Term 1
Definition 1
- Term 2 with inline markup
Definition 2
{ some code, part of Definition 2 }
Third paragraph of definition 2.
Term 1
: Definition 1
Term 2 with *inline markup*
: Definition 2
{ some code, part of Definition 2 }
Third paragraph of definition 2.
Links
This is an internal link to the References section and this is a link to an external Markdown Guide .
This is an internal link to the [References](#references) section and this is a link to an external [Markdown Guide](https://www.markdownguide.org/basic-syntax/).
Images
Images in Markdown suck. You can only specify the Alt Text - no sizing so the image will appear full size. You can use Hugo’s figure shortcode, but again that is pretty limited as it doesn’t handle responsive images well, so I wrote my own figure shortcode to override Hugos.
![Image Caption](/gallery/2017/2017_01_7-8/20170107-_O156345_DxO-w1536.jpg "Alt Text")
This much better, class=“float-right” does what it is meant to do.
width=“50%” works nicely too.
By default my shortcode will generate a range of responsive JPG and WEBP sizes: 400px, 600px, 800px, 1024px, 1536px and 2048px.
{{< figure src="/gallery/2017/2017_01_7-8/20170107-_O156345_DxO.jpg" caption="Image with custom shortcode" class="float-right" width="50%" >}}
Panoramas
My custom shortcode for klrpano takes the source and the type is the xml file generated by krpano
{{< krpano src="/panoramas/20150208-_O154434_DxO_panorama" caption="Thurat Spires and Kanangra Walls Partial Panorama - 8 Feb 2015 - 53 MPixels" type="pano" >}}
Videos
I have also created a video shortcode - which is simply the standard HTML video tag wrapped in a shortcode. Sizing is set by CSS:
{{< video src="/videos/Rocky_Creek_2012_Tambo_Pt1.mp4" type="video/mp4" >}}