Markdown

Introduction

Markdown is a lightweight markup language used by Github. It’s designed to be easy to convert to HTML and simulate rich-text in a plain-text environment.

Markdown is useful to know because you'll soon find you can use it in many places you might not expect to be able to. What you write on GitHub and StackOverflow(https://stackoverflow.com/help/formatting). For instance, you can write italic or bold text.

Other places have documented Markdown, so I'd look elsewhere if you're interested in [mastering Markdown][]. Consider this page more of a place to "reference" Markdown, rather than learn it.

To learn Markdown, check out these resources:

Lists

Quotations

  // it's even formatted as real java code
if (three_backticks) {
  inside = code_block
}

Similarly, this is inline code

Making Tables

You can create tables by assembling a list of words and seperating them by the | character.

The first row should include some hyphens - to underline it.

Header One | Header Two
---------- | ----------
It doesn't matter how long this content is | Reason: pipe seperates each block!
After you add a newline | You can write the next row in the table!

Output

Header One Header Two
It doesn't matter how long this content is Reason: pipe seperates each block!
After you add a newline You can write the next row in the table!

Text-Alignment in Tables

You can change the way a table's text aligns by appending a : to the dashes below your title

| Left-aligned | Center-aligned | Right-aligned |
| :---         |      :---:     |  ---:         |
| Check        | This           | Out           |
Left-aligned Center-aligned Right-aligned
Check This Out

Escaping Characters in Markdown

Some characters are special by default, and must be escaped by the escape character \ in order for Markdown to interpret them literally. This is only required when Markdown would otherwise interpret the character specially, for instance, to type *literal asterisks* one must type \* literal asterisks\*

Character Name
\ escape
` code block
* emphasis
_ emphasis
{} heading ID
[] task list
() link embed
# heading
+ plus sign
- minus sign (hyphen)
. dot
! image embed
` `

Escaping angle brackets <>

Angle brackets <> are a little trickier to render, since a markdown page is converted into HTML, which treats angle brackets as parts of a tag. Luckily, GitHub Flavored Markdown (GFM) supports escaping curly brackets.

To write <tag> in GFM, type \<tag\>. This even works with whitespace in the middle. To write <two words> in GFM type \<two words\>.

Hugo supports element IDs for headings on a page.

Specifying custom heading IDs can be done as follows:

Footnotes

Footnotes are an extension to Markdown, but is less commonly implemented than other extensions. They are supported by PHP's Markdown Extra but not by Commonmark, nor by GitHub Flavored Markdown (GFM). It can enabled in hugo's configurations for Goldmark, the library used by hugo to generate HTML from Markdown.

An example is provided below:

This example uses the IEEE Reference List[^1] format 
to create a footnote for a citation[^2] of a web article.

[^1]: "Reference List." Purdue Owl. <https://owl.purdue.edu/owl/research_and_citation/ieee_style/reference_list.html>
[^2]: "Citation." Wikipedia. <https://wikipedia.org/wiki/Citation>

Output:

This example uses the IEEE Reference List1 format to create a footnote for a citation2 of a web article.


  1. "Reference List." Purdue Owl. https://owl.purdue.edu/owl/research_and_citation/ieee_style/reference_list.html ↩︎

  2. "Citation." Wikipedia. https://wikipedia.org/wiki/Citation ↩︎