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:

• Communicating using Markdown
• Mastering Markdown

Lists

• Creating an ordered list

  1. Alpha
  1. Bravo
  1. Charlie
  

  Output

  1. Alpha
  2. Bravo
  3. Charlie

• Creating an unordered list

  * Alpha
  * Bravo
  * Charlie
  

  Output

  • Alpha
  • Bravo
  • Charlie

Quotations

• Creating a quotation

  > e=mc^2
  >
  > -- Funny Hair Science Man
  

  Output

  e=mc^2

  -- Funny Hair Science Man

• Creating a blockquote

  > It was the best of times
  > it was the worst of times
  

  Output

  It was the best of times it was the worst of times

• Nested quotes

  > This is the most recent message
  > 
  > Best,
  > Alpha
  > 
  > > This is the reply to the original message
  > > 
  > > Best,
  > > Bravo
  > >
  > > > This is the original message
  > > > 
  > > > Best,
  > > > Alpha
  > > > 
  

  Output

  This is the most recent message

  Best, Alpha

  This is the reply to the original message

  Best, Bravo

  This is the original message

  Best, Alpha

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

Similarly, this is inline code

Tables

Tables are an extension of the original Markdown spec. They are, however, supported on GitHub.

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 |
| ---------- | ---------- |
| This content can be as long as you want | Reason: it won't seperate until it sees this pipe: | |
| After you add a newline | You can write the next row in the table! |

Output

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           |

To learn more, see Organizing information with tables

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\*

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:

• Generating a custom heading ID

  ## This Section {#this-section}
  ## Other Content {id="other-content"}
  

  Output

  <h2 id="foo">Reference A</h2>
  <h2 id="bar">Reference B</h2>
  

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 List¹ format to create a footnote for a citation² of a web article.