The Markdown elements outlined in John Gruber’s design document is outlined here¹ at https://www.markdownguide.org/basic-syntax/.

Extended Syntax² for advanced features that build on the basic Markdown syntax

• A Markdown here cheatsheet³ at https://github.com/adam-p/markdown-here.

Block elements:

• A paragraph is created by 1 or more blank lines.

• Headings use the hash symbol # with 1 to 6 hashes corresponding to HTML headings levels 1 to 6.

• Usually use the > to create a **block quote ** . This does not seem to work so easily with Hugo though.

Without the threat of punishment, there is no joy in flight.

Lists

• Lists *, - or + to create an unordered list

• list items using a *

• list item using a +

• Lists items beginning with a number and a dot to create an ordered list.

1. list item 1 using 1.
2. List item 2 using 2.

Task Lists

• a task list item
• incomplete task item
• completed

Tables

See notes on organising information with Tables⁴

A simple markdown table:

• There must be at least 3 dashes --- separating each header cell. Outer pipes | can also be used |---| but these are optional. The markdown should still line up nicely without them.

header 1 | header 2 | header 3
--- | --- | ---
1 | 2 | 3
a|b|c
Banana |apple |orange

renders as:

With outer pipes |:

Colons : can be used to align columns:

• Adding a : before the dashes to left-align :-----,
• Adding a : after the dashes to right align ----:
• Adding : at both ends of the dashes to centre the content :-------:.

| Left-aligned        | Centre-aligned        | Right-aligned      |
| :------------ |:---------------:| -----:|
1 | 2 | 3|
|a|b|c|
|Banana |apple |orange|

Renders as:

Inline Markdown can be used in a markdown table:

Code fences

Use three backticks ` before and after the code block. Add a language identifier after the opening backticks to use the appropriate syntax highlighting.

import pandas as pd
import numpy as np

Footnotes

Footnotes are now supported in Markdown fields. Footnotes allow you to reference relevant information without disrupting the flow. (This would have been so useful to have known before for college projects!). Footnotes are added using [^fn] with the number of the footnote, for example [^fn1].

See GitHub.blog/changelog ⁵

Blockquotes

To create a blockquote you put a > in front of a paragraph.

Try to put a blank line before and after a blockquote. Blockquotes can have several lines. Add a > on the blank lines between paragraphs.

I’m not sure about blockquotes and Hugo. I think a shortcode might need to be used.

Three consectutive * or - will create a horizontal rule. Put a blank line before and after, otherwise a heading is created.

YAML front matter

--- at the top of the article to use a meta block. Finish the block with --- also.

Table of Contents

[toc]

Span Elements

Links:

• You can insert a URL as a link wrapped in <> although it not always necessary for standard URLs.

For example https://angela1c.com or <https://www.angela1c.com> produces https://angela1c.com or https://www.angela1c.com

• Inline links using [] around the link text and () around the URL that the link points to.
• [link text](www.example.com) An optional title can be given that is displayed as a tooltip when you hover over the link.

For example this is an example inline link inline link with an optional title and this is an example inline link without the optional title.

This will produce an HTML link with href and optional title attributes. <a href="https://www.angela1c.com/" title="my website>.

• Internal links use a hash symbol # to reference an internal link using the name of a header element as the href. (This can work together with [toc] for creating a table of contents from the headers.).

For example [link to "Block Elements" section on this page](#block-elements).

Click this link to “Block Elements” section on this page

• Reference-style ⁶ links are a special kind of link that make URLs easier to display and read in Markdown. Reference-style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere else in the file to keep the text easy to read.

Reference links use a second set of square brackets. The actual link can then be defined anywhere else in the document. The link text will be used as the name of the link. This is useful for filling in the actual URL later.

For example:

```
[my website][] 
```
Then somewhere else in the document:
```
[my website]: https://www.angela1c.com   
```


[my website][]

Note the URL was defined below.

[my website]: https://www.angela1c.com 

• Images can also be used as links by using a ! before the start of the link. For example ![alt text](/path/to/image "an optional title")

It is slightly different in Hugo.

• To emphasise text wrap it in * or _ to produce a HTML <em> tag. (To use a literal asterisk or underscore where it could be taken as an emphasis delimiter, escape it using a backslash escape \*.)

• To make text strong use double asterisks or double underscore. This will wrap the text in a HTML <strong> tag.

• To strikethrough text surround the text with double tilda: ~~strikethrough~~.

There is no markdown code for underline, although HTML underline tag <u> could be used. (using shortcodes with Hugo or raw HTML)

• Inline code wrap it in backticks. For example import numpy as np is wrapped in a pair of backticks. `some code`.

  (To show the backtick ` here, I use a backslash \ to escape.)

In general, to display a literal character that would otherwise be used to format text in a Markdown document, add a backslash () in front of the character.

* Without the backslash, this would be a bullet in an unordered list.

Maths Equations

• Maths blocks

• LaTeX mathematical expressions can be rendered. See LaTeX Mathematics reference on Wikipedia. ⁷

• Install Markdown+Math⁸ extension for VS Code.

• Surround the expressions with double dollar symbols $$

Some examples:

$$\LaTeX$$

$$\int_\Omega \nabla u \cdot \nabla v~dx = \int_\Omega fv~dx$$

$$P_{in}=\frac{V_{in}^2}{R_{1}}$$

$$ a \times b $$

$$ a \cdot b $$

$$x\pm2$$ $$2\div3$$ $$\frac{2}{3}$$ $$\sqrt(2)$$

$$ x{^2} $$ $$x^2$$ $$n_1$$ $$n_{k+1}$$ $$e^x$$

• For inline maths surround the expression in single dollar signs $.

• $\mathbb{N}$ for the set of natural numbers

• $\mathbb{R}$ for the set of real numbers

• $\Omega$ Omega

• $\cdot$

• $\int_n$

• $\lim_{x \to \infty} \exp(-x) = 0$

Emojis

Emojis can be simply copied and pasted into Markdown.

😁 😉 😜

In Hugo you can enable emojis in the configuration file and then use the emoji codes. See the Emoji CheatCheat⁹ for supported emojis.

☺️ 😏 😍 😘 😚 😳 😌 😆 😁 😉 😜 🌵 😊 ⛺

HTML Symbols, Entities and ASCII Character codes

HTML Symbols, Entities and ASCII Character Codes can be included in a markdown document.

HTML Arrows¹⁰ is a comprehensive reference website for finding HTML symbol codes and entities, ASCII characters and Unicode hexadecimal values to use in your web design.

Hex codes, HTML codes and HTML entities can be used in raw HTML within markdown.

Copyright symbol:

Some other symbols

Iframes

iframes can be embedded into a markdown document by wrapping it in a shortcode that allows raw HTML.

• markdownguide basic syntax

• Markdown Cheatsheet