↑

Markdown Guide

Basic syntax: https://www.markdownguide.org/basic-syntax/#horizontal-rules

John Gruber’s Markdown: https://daringfireball.net/projects/markdown/

Extended Markdown (Flavors of Markdown):

When markdown is published on GitHub, it is rendered using a markdown variant called GitHub Flavored Markdown (or GFM). GFM supports most of the markdown constructs you are familiar with from Pandoc markdown, but it doesn’t have support for more advanced technical writing features like citations, footnotes, and definition lists.

Pandoc’s Markdown: https://pandoc.org/MANUAL.html#pandocs-markdown

Quarto Markdown: https://quarto.org/docs/authoring/markdown-basics.html#lists

kramdown: https://kramdown.gettalong.org/syntax.html

GitHub markup: https://github.com/github/markup

Comments

<! --# Comments go here -->

Escape backticks

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

  • To escape one backtick, enclose it with 2 backticks and space before and after `` `
  • To escape three backticks, enclose them with 4 backticks and space before and after. ```
A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

A triple backticks: ```` ``` ````

The line below is indented by at least 4 spaces.

​ ```python

​ def function():

​ print (“Yes”)

​ ```

GFM

GitHub Flavored Markdown

Codeblocks can sometimes break ordered lists (i.e. the list always returns to 1). To prevent this, you can do the following.

  1. Add a linebreak between the list item and the code-block, and indent the code-block by 4 spaces.

    Adding blank lines surrounding code chunks is recommended by Rmd to increase readability.

    1. Number 1
   
    ```python
    print("Hello World")
    ```

    text after code block1
   
2. Number 2
   
    ```ruby
    puts 'Hello World'
    ```

    text after code block2
   
3. Number 3
   
    ```c
    printf("Hello World");
    ```
       
    text after code block3

  2. Do not add a linebreak, but have the code-block aligned with the indentation of the line item.

    1. Number 1
   ```python
   print("Hello World")
   ```
   text after code block1
   
2. Number 2
   ```ruby
   puts 'Hello World'
   ```
   text after code block2
   
3. Number 3
   ```c
   printf("Hello World");
   ```
   text after code block3

Will be rendered into the following:

  1. Number 1 
    print("Hello World")

    text after code block1

  2. Number 2 
    puts 'Hello World'

    text after code block2

  3. Number 3 
    printf("Hello World");

    text after code block3

Ref:

Equations

Note that for markdown block equations, need to add a blank line before and after $$. Otherwise, the equation will be rendered as inline.

Typora support TeX-style references, i.e., \label{ref1}\tag{1}. Note that you must add a number using \tag{}; otherwise, the equation won’t be numbered and therefore cannot be cross-referenced. This is like you need to number the table or figure in order to cross-reference them.

Here is a labeled equation:

\[x+1\over\sqrt{1-x^2} \label{ref1}\tag{1}\]

This is a reference : $\eqref{ref1}$

Here is a labeled equation:

$$
x+1\over\sqrt{1-x^2} \label{ref1}\tag{1}
$$

This is a reference : $\eqref{ref1}$
  • When you add custom \tag{1}, you don’t have to surround your equations within \begin{equation} environments.
  • If you want automatic numbering, you must surround your equations within \begin{equation} environments. See the example below.
Here is an AR(1) model, 
$$
\begin{equation}
X_t=\phi_1 X_{t-1} + \varepsilon_t.\label{AR1}
\end{equation}
$$

Let $\phi(L)=1-\phi_1 L\,,$ then we can express the innovation $\eqref{AR1}$ as ...

Here is an AR(1) model, \(\begin{equation} X_t=\phi_1 X_{t-1} + \varepsilon_t.\label{AR1} \end{equation}\)

Let $\phi(L)=1-\phi_1 L\,,$ then we can express the innovation $\eqref{AR1}$ as …

Note that the automatic numbering starts from 1, ignoring any eqns with custom \tag{1}. So if you provide custom \tag{}, make sure you don’t use numbers, you can use stars instead.

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column.

Cell widths can vary, just use different relative length of hyphens.

| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

Bullet list

You can make a bulleted list by starting each line with a - or * or + character followed by a space. You can make a numbered list by starting each line with a 1. followed by a space.

Markdown need an Empty line before a list.

This will not work

* Item 1

* Item 1

* Item 1

* one
* two
* three

This will produce a “compact” list. If you want a “loose” list, in which each item is formatted as a paragraph, put spaces between the items:

* one

* two

* three

Identation is essential to bullet lists in markdown as it indicates bullet levels.

You can make a nested section of a list by adding two spaces before the bullet or number character.

  • four spaces or one tab work before the bullet too.
  • It is possible to add one blank line between different levels to increase readability.
* unordered list
    + sub-item 1 
    + sub-item 2 
        - sub-sub-item 1
  • unordered list
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1

  • You can still indent a paragraph even if you don’t need a new bullet point. The indentation indicates that this paragraph belongs to the preceding point.

    • You can also nest other elements like blockquotes or code blocks.
    1. Ingredients
  
    - spaghetti
    - marinara sauce
    - salt
  
2. Cooking
  
   Bring water to boil, add a pinch of salt and spaghetti. Cook until pasta is **tender**.
  
3. Serve
  
   Drain the pasta on a plate. Add heated sauce. 
  
   > No man is lonely eating spaghetti; it requires so much attention.
  
   Bon appetit!

    1. Ingredients

      • spaghetti
      • marinara sauce
      • salt

    2. Cooking

      Bring water to boil, add a pinch of salt and spaghetti. Cook until pasta is tender.

    3. Serve

      Drain the pasta on a plate. Add heated sauce.

      No man is lonely eating spaghetti; it requires so much attention.

      Bon appetit!

  • If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output.

  • Letter-ordered lists are NOT a part of standard markdown. The letters will only appear when rendering the markdown using an markdown extension or by using CSS.

Q: How to add a horizontal rule between list items without breaking out of the bullet list?

A: Two options:

  • Use <hr> html tag
  • Indent the horizontal rule.
- First point
  ---

- Second point

or using html tag
- First point
  <hr>
- Second point

Start numbering at a number other than 1

Jekyll uses Kramdown as Markdown parser that support setting custom attributes (see docs). And html5 support start attribute that change start number of ordered list see MDN.

The markdown file need to look like this:

1. First

Some text and other stuff

{:start="2"}
2. Second

Othe stuff

will be rendered into:

  1. First

Some text and other stuff

  1. Second

Other stuff

ref: https://stackoverflow.com/a/48612359

fancy_list extension

This is a pandoc extension which provides special list numbering formats like: uppercase and lowercase letters and roman numerals, while original markdown only supports Arabic numerals.

List markers may be enclosed in parentheses or followed by a single right-parenthesis or period. They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces.

Supported list markers by Pandoc extension fancy_lists
1) First item
A. Second item
(a) Third item

ref: https://pandoc.org/demo/example33/8.7-lists.html

Horizontal rules

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

  • The rendered output of all three looks identical.
***

---

_________________
  • For compatibility, put blank lines before and after horizontal rules.
✅ Do this ❌ Don’t do this
Try to put a blank line before …
---
… and after a horizontal rule.		 Without blank lines, this would be a heading.
---
Don’t do this!

Backquotes

To create a blockquote, start a line with greater than > followed by an optional space.

  • To keep the quote in one block, blank lines inside the quote must contain the > character too.

[text](https://url) create a text linked to the url in parentheses.

To quickly turn a URL or email address into a link, enclose it in angle brackets.

<fake@example.com> will show like fake@example.com

Note that urls in markdown cannot handle special characters, such as space, parenthesis, pipes. It is suggested to use a html tag <a href="">link</a> if your markdown supports html. Otherwise, need to

  • replace space with %20
  • replace parenthesis with %28

Reference-style links use a second set of square brackets [text][id], inside which you place a label of your choosing to identify the link.

Q: Why we use reference-style links?

A: The point of reference-style links is not that they’re easier to write. We aim to keep the text free from long URLs, making it easier to read.

[id] is a label used to point to the link you define somewhere else in your document, usually end of file to keep your text easier to read.

This is an example of referenc link: **[text][id]**.

This is an example of referenc link: text.

Link definition

The link definition can be placed anywhere after a blank line, but is generally near the bottom. You can also put them immediately after each paragraph in which they’re used.

Definition identifiers may consist of letters, numbers, spaces, and punctuation. They are not case sensitive.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/  "Optional Title Here"
  • put your label in square brackets, followed immediately by a colon and at least one space.
  • write your url for the link, which you can optionally enclose in angle brackets, e.g., <http://example.com/>.
  • you can specify an optional title, enclosed in double quotes, single quotes, or parentheses. It is a reminder of yourself what the website is about. Also when you hover your cursor above the link, the title will show.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word “Google” to the google.com web site, you could simply write:

[Google][]

And then define the link:

[Google]: http://google.com/
  • Link names may contain spaces.

Phone and email links

Call me [Call Me!](tel:1111111) using markdown or <a href="tel:1111111">Call Me!</a> using html.

example@example.com [example@example.com](mailto:example@example.com) or <a href="mailto:example@example.com">example@example.com</a>

Cross References

Internal Links to sections within the same file.

  • Link to title/heading/section

    You can use # to create links towards any headings in your markdown file.

    # This is a title
  
...
...
...
  
  
A [link](#this-is-a-title) to jump towards target heading

    Note that:

    • # for all heading levels, including level 2, 3 …

    • no space between # and anchor name;

      delimited by hyphens if multi-word;

    • anchor tag names must be lowercase

    [click on this link](#my-multi-word-header)
  
### My Multi Word Header

    If sections have special characters, you need to remove those special characters when you add the references.

    # 1. Python
  
# 2. c++
  
# 3. c++11
  
# 4. asp.net-core
  
You can add a reference by using:
[1. Python](#1-python)
[2. c++](#2-c)
[3. c++11](#3-c11)
[4. asp.net-core](#4-aspnet-core)

    Note how asp.net-core becomes aspnet-core, 1. python becomes 1-python, etc.

  • Manually added section IDs ✅

    This is the most reliable way to create links to sections in markdown.

    To avoid the hassle of escaping special characters, and ensure that when you change the title, the link will still work, it is recommended to manually add an ID to a section.

    To add an ID to a section: use the {#id} syntax at the end of the header line. For example:

    ## My Section Title {#my-section-id}
  
This is a section with a custom ID.
  
[Link to My Section](#my-section-id)

  • Link to named anchor

    This works not only for headings, but also for any text in the document.

    The markdown solutions are not universal, may act differently depending on the markdown implementation.

    In such cases, if you want a portable solution, you could use HTML.

    You define named anchors using raw HTML, for example: <a id="Chapter1"></a>. It can be put before any header, or in the same header line.

    • Source: the target text to which you want to link to, place the following tags before the text:

      • <a id="name-of-anchor"></a> or
      • <a name="name-of-anchor"></a>

      If the source is a heading, then use

      • <h2 name="name-of-anchor">Level 2 heading</h2> or

      • wrap the anchor point around the heading

        Note that you need to add an empty line between <a> and the heading. Otherwise, the heading won’t be rendered correctly.

        Tags surround heading
<a name="level3-heading">
      
### Level 3 heading
</a>
      
Tags before heading
<a name="level2-heading-before"></a>
      
## Level 2 heading
      
Tags on the same line with heading
## Level 2 heading <a name="level2-heading-same-line"></a>

    • Reference:

      • Use html style tags <a href="#name-of-anchor">Link to Anchor</a> to link to the target text. Or,
      • [Link to Anchor](#name-of-anchor) pure markdown
      • Note the # before the label.

    Use command + click to jump to target headings, or open them in Typora, or open in related apps.

    <a id="anchor"></a> Anchor
  
<a href="#anchor">Link to Anchor</a>

Cross-references to another file: use html tag <a href="<path-to-file>/file.html#anchor">Link to another file</a>

  • Note that for Jekyll sites, need to enclose the url root path with {{site.baseurl}}, e.g.,
 
<a href="{{site.baseurl}}/2023/10/04/Markdown.html#cross-references">Markdown: Cross References </a> for more examples.

Typeface

Format Quoted by
bold **text** (text)
italic *text* or _text_ (text)
bold and italic ***text*** (text)
strikethrough ~~text~~ (text)
underline <u>text</u> (text)

Start a new line (line break) without starting a new paragrah:

  • \ + soft Enter (shift + Enter); or,
  • two empty spaces at the end of a line ␣␣, followed by a soft Enter; or,
  • html tags <br /> or &nbsp;

Insert vertical space

  • To create a blank line, use &nbsp; (followed by a blank line).

    This will add a large vertical space. If you feel it is too large, use the following solution.

  • <div style="height:3px;"><br></div> use whatever px you want use in html

Non-Breaking Spaces

In markdown and html non-breaking space can be inserted by &nbsp; in LaTeX output it will be a ~ character.

Use html entity code to add special characters in Markdown

|checked|unchecked|crossed|
|---|---|---|
|&check;|_|&cross;|
|&#x2611;|&#x2610;|&#x2612;|
checked unchecked crossed
&check; _ &cross;
☑ ☐ ☒

html Codes Table

Code Blocks

Note that consecutive code blocks that are only separate by blank lines are merged together into one code block:

Here comes some code

This text belongs to the same code block.

If you want to have one code block directly after another one, you need to use an EOB marker to separate the two:

Here comes some code
^
This text belongs to the same code block.

The End-Of-Block (EOB) marker – a ^ as first character on an otherwise empty line – is a block level element that can be used to specify the end of a block-level element even if the block-level element, after which it is used, would continue otherwise.

For example, the following gives you one list with two items:

* list item one

* list item two

By using an EOB marker, you can make two lists with one item each:

* list one
^
* list two

Kramdown-specific syntax

Attribute List Definitions

Attribute List Definitions (ALDs) are where you can define a named attribute set once and then reuse it.

ALD examples:

{:ref-name: #myid .my-class}

Elements of ALDs:

  • :ref-name: is the identifier of the element.

    This is a reusable named attribute list you can apply later with just {:ref-name}. It is like a CSS class shortcut.

  • Followed by attributes definitions.

    • #myid is an id attribute.
    • .my-class is a class attribute. Multiple class attributes can be defined, e.g., {:id: class="cls1" .cls2}

  • ALDs starts with { and and ends with }.

Use examples:

  • Definition

    {:note-style: .note data-type="info"}

  • Later you can apply it

    > This is a note.
{:note-style}

    which will be rendered into:

    <p class="note" data-type="info">This is an important note.</p>

Attribute Lists

The Block Inline Attribute List is used to attach attributes to a block-level element and the Span Inline Attribute List is used to attach attributes to a span-level element.

This is where you attach attributes directly to a block/span.

  • Put directly before or after the block-level element to which the attributes should be attached.
    • If a block IAL is directly after and before a block-level element, it is applied to the preceding element.

Block Inline Attribute Lists (IAL)

Syntax:

{: #id .class key=value}

Use examples:

Paragraph text
{: #myid .highlight data-type="note"}

Note that:

  • The block IAL is ignored in all other cases, for example, when the block IAL is surrounded by blank lines.
  • Inline Attribute Lists take precedence over equally named key-value pairs in referenced Attribute List Definitions.

Span Inline Attribute Lists

A span IAL (or two or more span IALs) has to be put directly after the span-level element to which it should be applied, no additional character is allowed between, otherwise it is ignored and only removed from the output.

Use examples:

This *is*{:.underline} some `code`{:#id}{:.class}.
A [link](test.html){:rel='something'} and some **tools**{:.tools}.

Pandoc

Useful docs:

Pandoc is a Haskell library for converting from one markup format to another, including, but not limited to, various flavors of Markdown, HTML, LaTeX and Word docx.

Add Attributes

Header Attributes

# Header text {#id .class .class key=value  key=value}

Unnumbered header

# My heading {-}

is just the same as

# My heading {.unnumbered}

Fenced code block attributes

<pre id="mycode" class="haskell numberLines" startFrom="100">
  <code>
  ...
  </code>
</pre>

Pandoc does not require a specific order of the attributes, you can start with #id or .class. Note that Kramdown requires the #id to be the first attribute.

Shortcut

```haskell {#mycode .numberLines startFrom="100"}
```
equivalent to
```{#mycode .haskell .numberLines startFrom="100"}
```

Short attribute syntax

.classname[]
#id[]
.class1.class2#id[]
  • creates a <div> or with the specified class(es) and id.
  • .classname[] is shorthand for creating a div block with a class in Pandoc/Quarto/Reveal.js Markdown.
  • What does the empty square brackets [] do?

    • Pandoc and Quarto: the empty square brackets [] are required to indicate that it is a block element. Without the square brackets, it will be treated as an inline element.

      Put key=value inside the square brackets if you want to add more attributes.

      The content of the block (the text you want to style) goes after the attribute declaration, not inside the brackets.

    • xaringan and Reveal.js: put content in the square brackets []

Simple example:

.red-bg[]
This is highlighted text.

will be rendered into

<div class="red-bg">
This is highlighted text.
</div>

Example with multiple attributes:

.red-bg#intro[data-level="2"]
This text is highlighted with class "red-bg", id "intro", and a data attribute.

will be rendered into

<div class="red-bg" id="intro" data-level="2">
This text is highlighted with class "red-bg", id "intro", and a data attribute.
</div>

Inline Attributes

[text]{.class key="val"}

will be rendered into

<span class="class" key="val">text</span>

Example:

[Small caps]{.smallcaps}

will be rendered into

<span class="smallcaps">Small caps</span>

CommonMark

Useful docs:

Attribute Syntax:

https://talk.commonmark.org/t/consistent-attribute-syntax/272