Marrrkdown Rules
Let’s face it: Writ'n rrrambl'n fer th' web be tiresome. WYSIWYG editors help alleviate this task, but they generally result 'n horr'ble code, or worse yet, ugly web planks.
Marrrkdown be a better way t' write HTML, without all th' complexities an' ugliness that usually accompanies it.
Some o' th' key benefits be:
- Marrrkdown be simple t' learn, wit' minimal extra characters so it’s also quicker t' write rrrambl'n.
- Less chance o' errors when writ'n 'n Marrrkdown.
- Produces valid HTML output.
- Keeps th' rrrambl'n an' th' visual display separate, so ye cannot mess up th' look o' yer ship.
- Write 'n any text editor or Marrrkdown applicat'n ye like.
- Marrrkdown be a joy t' use!
John Gruber, th' author o' Marrrkdown, puts it like this:
Th' overrid'n design goal fer Markdown’s formatt'n rules be t' make it as read'ble as poss'ble. Th' idea be that a Markdown-formatted document should be publish'ble as-is, as plain text, without look'n like it’s been marked up wit' tags or formatt'n instruct'ns. While Markdown’s rules has been influenced by several exist'n text-to-HTML filters, th' single biggest source o' inspirat'n fer Markdown’s rules be th' format o' plain text email.
John Gruber
Smarrrt Arrrse
Bookmark this plank fer easy future reference!
Standard an' Extensions
If not otherwise noted, th' shown examples adhere t' th' CommonMark standard. In addit'n th' theme supports th' follow'n extensions that can be activated 'n yer hugo.toml
or be built into th' theme:
Paragraphs
In Marrrkdown yer rrrambl'n usually spans th' whole avail'ble document width. This be called a block. Blocks be always separated by whitespace t' their adjacent blocks 'n th' result'n document.
Any text not start'n wit' a special sign be written as normal, plain text paragraph block an' must be separated t' its adjacent blocks by empty lines.
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Result
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Head'ns
A bloody idea be t' structure yer rrrambl'n us'n head'ns an' subhead'ns. HTML-head'ns from h1
through h6
be constructed wit' a #
fer each level.
In Hugo ye usually don’t use h1
as this be generated by yer theme an' ye should only have one such element 'n a document.
# h1 Head'n
## h2 Head'n
### h3 Head'n
#### h4 Head'n
##### h5 Head'n
###### h6 Head'n
Result
h1 Head'n
h2 Head'n
h3 Head'n
h4 Head'n
h5 Head'n
h6 Head'n
Horizontal Rules
T' further structure yer rrrambl'n ye can add horizontal rules. They create a “thematic break” between paragraph blocks. In Marrrkdown, ye can create it wit' three consecutive dashes ---
.
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
---
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Result
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Blockquotes
Quotat'ns
For quot'n blocks o' rrrambl'n from another source within yer document add >
before any text ye want t' quote.
Blockquotes can also be nested.
> Donec massa lacus, ultricies a ullamcorper 'n, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipisc'n elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis 'n dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
Result
Donec massa lacus, ultricies a ullamcorper 'n, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
Sed adipisc'n elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis 'n dolor tincidunt mollis ac eu diam.
Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
GitHub Alerts
GFM Since Cap'n Hugo 0.132.0 GitHub alerts be also supported. Please note, that color'n an' ay'cons o' severities may defer between GitHub an' this theme.
If ye be 'n need o' more advanced opt'ns t' style yer alerts, like ay'cons, use th' notice shortcode.
> [!CAUTION]
> Advises about risks or negative outcomes o' certain act'ns.
> [!IMPORTANT]
> Key informat'n users need t' know t' achieve their goal.
> [!INFO]
> Informat'n that users <ins>_might_</ins> find interest'n.
> [!NOTE]
> Useful informat'n that users should know, even when skimm'n rrrambl'n.
> [!TIP]
> Helpful advice fer do'n th'ns better or more easily.
> [!WARNING]
> Urgent info that needs immediate user attent'n t' avoid problems.
Result
Caut'n
Advises about risks or negative outcomes o' certain act'ns.
Important
Key informat'n users need t' know t' achieve their goal.
Ahoi
Informat'n that users might find interest'n.
Avast
Useful informat'n that users should know, even when skimm'n rrrambl'n.
Smarrrt Arrrse
Helpful advice fer do'n th'ns better or more easily.
Arrr
Urgent info that needs immediate user attent'n t' avoid problems.
Obsidian Callouts
Obsidian Since Cap'n Hugo 0.134.0 Obsidian callouts be also supported. Which enables configur'ble title text an' expand/collapse.
If ye be 'n need o' more advanced opt'ns t' style yer alerts, like ay'cons, use th' notice shortcode.
> [!tip] Callouts can have custom titles
> Like this one.
> [!tip] Title-only callout
> [!note]- Be callouts fold'ble?
> Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed
> [!note]+ Be callouts fold'ble?
> Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed
Result
Callouts can have custom titles
Text Markers
Bold
Ye can show importance o' a snippet o' text wit' a heavier font-weight by enclos'n it wit' two asterisks **
.
I am rendered wit' **bold text**
Result
I am rendered wit' bold text
Italics
Ye can emphasize a snippet o' text wit' italics by enclos'n it wit' underscores _
.
I am rendered wit' _italicized text_
Result
I am rendered wit' italicized text
Marked Text
Ye can mark text 'n th' predefined accent color o' yer stylesheet.
Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml
==Parts== o' this text ==are marked!==
HTML Ye can also use it by configur'n Hugo fer usage o' HTML.
<mark>Parts</mark> o' this text <mark>be marked!</mark>
Result
Parts o' this text be marked!
Inserted Text
Ye can mark text addit'ns t' exist'n text.
Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml
HTML Ye can also use it by configur'n Hugo fer usage o' HTML.
Th' <ins>hot, new</ins> stuff
Deleted Text
GFM Ye can do strikethroughs by enclos'n text wit' two tildes ~~
. See Hugo’s documentat'n remarks if ye want t' use this together wit' th' subscript rules.
~~Strike through~~ this text
Special Typesett'n
Text Substitut'n
Pants Ye can combine multiple punctuat'n characters t' single typographic entities. This will only be applied t' text outside o' code blocks or inline code.
Do'ble quotes `"` an' single quotes `'` o' enclosed text be replaced by **"do'ble curly quotes"** an' **'single curly quotes'**.
Do'ble dashes `--` an' triple dashes `---` be replaced by en-dash **--** an' em-dash **---** entities.
Do'ble arrows point'n left `<<` or right `>>` be replaced by arrow **<<** an' **>>** entities.
Three consecutive dots `...` be replaced by an ellipsis **...** entity.
Result
Do'ble quotes "
an' single quotes '
o' enclosed text be replaced by “do'ble curly quotes” an' ‘single curly quotes’.
Do'ble dashes --
an' triple dashes ---
be replaced by en-dash – an' em-dash — entities.
Do'ble arrows point'n left <<
or right >>
be replaced by arrow « an' » entities.
Three consecutive dots ...
be replaced by an ellipsis … entity.
Subscript an' Superscript
Ye can also use subscript an' superscript text. For more complex stuff, ye can use th' math
shortcode.
Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml
How many liters H~2~O fit into 1dm^3^?
HTML Ye can also use it by configur'n Hugo fer usage o' HTML.
How many liters H<sub>2</sub>O fit into 1dm<sup>3</sup>?
Result
How many liters H2O fit into 1dm3?
Keyboard Shortcuts
HTML Ye can use th' <kbd>
element t' style keyboard shortcuts.
Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> t' end yer shift early.
Result
Press STRG ALT DEL t' end yer shift early.
Lists
Unordered
Ye can write a list o' items 'n which th' order o' th' items does not explicitly matter.
It be poss'ble t' nest lists by indent'n an item fer th' next sublevel.
Ye may use any o' -
, *
or +
t' denote bullets fer each list item but should not switch between those symbols inside one whole list.
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Faucibus porta lacus fringilla vel
Result
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Faucibus porta lacus fringilla vel
Ordered
Ye can create a list o' items 'n which th' order o' items does explicitly matter.
It be poss'ble t' nest lists by indent'n an item fer th' next sublevel.
Marrrkdown will automatically number each o' yer items consecutively. This means, th' order number ye be provid'n be irrelevant.
1. Lorem ipsum dolor sit amet
3. Consectetur adipisc'n elit
1. Integer molestie lorem at massa
7. Facilisis 'n pretium nisl aliquet
99. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
17. Eget porttitor lorem
Result
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Integer molestie lorem at massa
- Facilisis 'n pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Tasks
GFM Ye can add task lists result'n 'n checked or unchecked non-click'ble items
- [x] Basic Test
- [ ] More Tests
- [x] View
- [x] Hear
- [ ] Smell
Definit'ns
PHP Definit'n lists be made o' terms an' definit'ns o' these terms, much like 'n a dictionary.
A definit'n list 'n Marrrkdown Extra be made o' a single-line term followed by a colon an' th' definit'n fer that term. Ye can also associate more than one term t' a definit'n.
If ye add empty lines around th' definit'n terms, additional vertical space will be generated. Also multiple paragraphs be poss'ble
Apple
: Pomaceous fruit o' plants o' th' genus Malus 'n th' family Rosaceae.
: An American computer company.
Orange
: Th' fruit o' an evergreen tree o' th' genus Citrus.
Ye can make juice out o' it.
: A telecommunicat'n company.
Ye can't make juice out o' it.
Result
- Apple
- Pomaceous fruit o' plants o' th' genus Malus 'n th' family Rosaceae.
- An American computer company.
- Orange
- Th' fruit o' an evergreen tree o' th' genus Citrus.
Ye can make juice out o' it.
- A telecommunicat'n company.
Ye can’t make juice out o' it.
Code
Inline Code
Inline snippets o' code can be wrapped wit' backticks `
.
In this example, `<div></div>` be marked as code.
Result
In this example, <div></div>
be marked as code.
Indented Code Block
A simple code block can be generated by indent'n several lines o' code by at least two spaces.
Be impressed by my advanced code:
// Some comments
line 1 o' code
line 2 o' code
line 3 o' code
Result
Be impressed by my advanced code:
// Some comments
line 1 o' code
line 2 o' code
line 3 o' code
Fenced Code Block
If ye want t' gain more control o' yer code block ye can enclose yer code by at least three backticks ```
a so called fence.
GFM Ye can also add a language specifier directly after th' open'n fence, ```js
, an' rules highlight'n will automatically be applied accord'n t' th' selected language 'n th' rendered HTML.
See Code Highlight'n fer additional documentat'n.
```js
{
name: "Claus",
surname: "Santa",
profession: "courier",
age: 666,
address: {
city: "North Pole",
postalCode: 1,
country: "Arctic"
},
friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};
```
Result
{
name: "Claus",
surname: "Santa",
profession: "courier",
age: 666,
address: {
city: "North Pole",
postalCode: 1,
country: "Arctic"
},
friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};
Tables
GFM Ye can create tables by add'n pipes as dividers between each cell, an' by add'n a line o' dashes (also separated by bars) beneath th' header. Avast that th' pipes do not need t' be vertically aligned.
| Opt'n | Descript'n |
|--------|-------------|
| data | path t' data files t' supply th' data that will be passed into templates. |
| engine | engine t' be used fer process'n templates. Handlebars be th' default. |
| ext | extension t' be used fer dest files. |
Result
Opt'n |
Descript'n |
data |
path t' data files t' supply th' data that will be passed into templates. |
engine |
engine t' be used fer process'n templates. Handlebars be th' default. |
ext |
extension t' be used fer dest files. |
Aligned Columns
Add'n a colon on th' left and/or right side o' th' dashes below any head'n will align th' text fer that column accordingly.
| Opt'n | Number | Descript'n |
|-------:|:------:|:------------|
| data | 1 | path t' data files t' supply th' data that will be passed into templates. |
| engine | 2 | engine t' be used fer process'n templates. Handlebars be th' default. |
| ext | 3 | extension t' be used fer dest files. |
Result
Opt'n |
Number |
Descript'n |
data |
1 |
path t' data files t' supply th' data that will be passed into templates. |
engine |
2 |
engine t' be used fer process'n templates. Handlebars be th' default. |
ext |
3 |
extension t' be used fer dest files. |
Links
Autolink
GFM Absolute URLs will automatically be converted into a link.
This be a link t' https://example.com.
Basic Link
Ye can explicitly define links 'n case ye want t' use non-absolute URLs or want t' give different text.
[Assemble](http://assemble.io)
For even further informat'n, ye can add an additional text, displayed 'n a tooltip on hover'n over th' link.
[Upstage](https://github.com/upstage/ "Visit Upstage!")
Link References
Links can be simplyfied fer recurr'n reuse by us'n a reference ID t' later define th' URL locat'n. This simplyfies writ'n if ye want t' use a link more than once 'n a document.
[Example][somelinkID]
[somelinkID]: https://example.com "Go t' example domain"
PHP Footnotes work mostly like reference-style links. A footnote be made o' two th'ns, a marker 'n th' text that will become a superscript number an' a footnote definit'n that will be placed 'n a list o' footnotes.
Usually th' list o' footnotes will be shown at th' end o' yer document. If we use a footnote 'n a notice box it will instead be listed at th' end o' its box.
Footnotes can contain block elements, which means that ye can put multiple paragraphs, lists, blockquotes an' so on 'n a footnote. It works th' same as fer list items, just indent th' follow'n paragraphs by four spaces 'n th' footnote definit'n.
That's some text wit' a footnote[^1]
[^1]: An' that's th' footnote.
That's some more text wit' a footnote.[^someid]
[^someid]:
Anyth'n o' interest goes here.
Blue light glows blue.
Result
That’s some text wit' a footnote
That’s some more text wit' a footnote.
Images
Basic Images
Images have a similar rules t' links but include a preced'n exclamat'n mark.
![Spock](https://octodex.github.com/images/spocktocat.png)
Like links, images can also be given a tooltip.
![Picard](https://octodex.github.com/images/jean-luc-picat.jpg "Jean Luc Picard")
Image References
Images can also be linked by reference ID t' later define th' URL locat'n. This simplyfies writ'n if ye want t' use an image more than once 'n a document.
![La Forge][laforge]
[laforge]: https://octodex.github.com/images/trekkie.jpg "Geordi La Forge"
Image Effects
Relearrrn This theme allows additional non-standard formatt'n by sett'n query parameter at th' end o' th' image URL. See th' image effects docs fer a detailed example an' how t' configure it.
Resiz'n
Add query parameter width
and/or height
t' th' link image t' resize th' image. Values be CSS values (default be auto
).
![Minion](https://octodex.github.com/images/minion.png?width=20vw)
![Minion](https://octodex.github.com/images/minion.png?height=50px)
![Minion](https://octodex.github.com/images/minion.png?height=50px&width=40vw)
CSS Classes
Add a query parameter classes
t' th' link image t' add CSS classes. Add some o' th' predefined values or even define yer own 'n yer CSS.
Shadow
![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=shadow)
Border
![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=border)
Left
![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=left)
Right
![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=right)
Inline
![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=inline)
![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=inline)
![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=inline)
![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=inline)
Combinat'n
![X-tocat](https://octodex.github.com/images/xtocat.jpg?classes=shadow,border,left)
Lightbox
Add th' query parameter lightbox=false
t' th' image link t' dis'ble th' lightbox.
![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)
Avast
If ye want t' wrap an image 'n a link an' lightbox=true
be yer default sett'n, ye have t' explicitly dis'ble th' lightbox t' avoid it t' hijack'n yer link like:
[![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)](https://octodex.github.com/#homercat)