Markdown can produce its own numbered and unnumbered lists, these can be mixed and nested as required. These lists are quite basic and don’t look very good (lists within the PracticalSeries Wikis use tables to give better structure and formatting, see section 10 for details).

Block quotes and alerts are used to highlight particular text.

⬆️ Top

Block quotations are areas of text that are highlighted to make them distinct from the normal body text, they look like this:

This is an extract from “Race to the Moon”: Cox, Catherine Bly & Charles Murray (1989). Published by Simon and Schuster. There is a Kindle version by the same authors, but it is just called Apollo.

Block quotations are so called because they often contain quotes or references to other works. In practice, block quotations can be used for any purpose.

GitHub displays block quotations with a 4 px wide grey bar on the left-hand side of the text area. The text is indented by 4.5 spaces and is in a grey colour: #59636E or rgb(89,99,110) that is lighter than the body text colour. Block quotation text is the same point size as body text.

Block quotations are created in Markdown by starting the line with a single greater than sign > followed by a space:

> First line
> 
> Second line

<blockquote>
  <p>First line</p>
  <p>Second line</p>
</blockquote>

A blank line with a leading greater than > can be used to separate paragraphs in a block quotation.

⬆️ Top

Block quotes can be nested by adding extra > at the start of the text:

> First level
>
>> Second level
>>
>>> Third level
>>>
>>>> Fourth level
>>>
>>> Third level
>>
>> Second level
>
> First level

<blockquote>
  <p>First level</p>
  <blockquote>
    <p>Second level</p>
    <blockquote>
      <p>Third level</p>
      <blockquote>
        <p>Fourth level</p>
      </blockquote>
      <p>Third level</p>
    </blockquote>
    <p>Second level</p>
  </blockquote>
  <p>first level</p>
</blockquote>

⬆️ Top

Block quotes can contain other Markdown elements such as headings, emphasis (bold, italic, underline &c.), they can also contain lists (GitHub supports lists in block quotes). The lists can be ordered or unordered (see section 8.3 and section 8.2). The following shows some examples:

> # Block Quotes
>
> With lists
>
> * List point 1
> * List point 2
>
> *Last **line***

<blockquote>
  <h1> Block Quotes </h1>
  <p> With lists</p>
  <ul>
    <li> List point 1</li>
    <li> List point 2</li>
  </ul>
  <p><em>Last <strong>line</strong></em></p>
</blockquote>

⬆️ Top

⬆️ Top

Unordered or unnumbered lists are the simplest form of list, they appear as indented lines with a point (•) at the start of the line:

• First point
• Second point
• Third point

Unordered lists are created in Markdown by starting the line with a single asterisk * followed by a space, a single dash - followed by a space or a single plus + followed by a space.

The following all work:

* First point
* Second point
* Third point

- First point
- Second point
- Third point

+ First point
+ Second point
+ Third point

<ul>
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ul>

Whichever delimiter you use, it must be the first character on the line (spaces in front of it will be ignored), any non-space character that precedes it will cause the line to render as normal text.

⬆️ Top

It is possible to nest unordered lists:

• Level 1 point 1
• Level 1 point 2
  • Level 2 point 1
  • Level 2 point 2
    • Level 3 point 1
• Level 1 point 3
• Level 1 point 4

Unordered lists are nested by indenting each list by at least two spaces (four is more conventional) before the delimiter for each additional level. The above is generated as follows:

* Level 1 point 1
* Level 1 point 2
    * Level 2 point 1
    * Level 2 point 2
        * Level 3 point 1
* Level 1 point 3
* Level 1 point 4

<ul>
  <li>Level 1 point 1</li>
  <li>Level 1 point 2</li>
  <ul>
    <li>Level 2 point 1</li>
    <li>Level 2 point 2</li>
    <ul>
      <li>Level 3 point 1</li>
    </ul>
  </ul>
  <li>Level 1 point 3</li>
  <li>Level 1 point 4</li>
</ul>

Nesting uses different bullet marks for the first three levels: black circle: ${\color{#000000}\text{⏺}}$, open circle: ${\color{#000000}\text{⭘}}$ and black square: ${\color{#000000}\text{⯀}}$. All subsequent nesting levels just use the black square:

• Level 1
  • Level 2
    • Level 3
      • Level 4
        • Level 5

Unordered lists can be indented as far as you like.

⬆️ Top

The type of bullet point used is fixed in Markdown: a black circle for the first level, open circle for the second and black square for all other layers.

HTML allows the type of bullet point to be selected (within limits) with the use of the type attribute. The type attribute can specify a disk, a circle, a square, or none.

<ul type = "disk">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ul>

<ul type = "circle">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ul>

<ul type = "square">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ul>

<ul type = "none">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ul>

⬆️ Top

In terms of spacing, the point mark (•) is indented three spaces from the left edge of the text area, the text following the point mark is indented a further two spaces.

If the line of text following the point wraps at the end of a line, the text will maintain the correct indentation as follows:

• Point 1
• Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus. Nam ultricies non sapien ac rutrum.
• Point 3

Here the second point wraps at the end of the line, but maintains the correct indentation.

Each nested level indents the list by a further seven spaces before the bullet point, the text following the bullet point is always indented two spaces.

⬆️ Top

A slightly misleading heading.

If you start an unordered list with a number let’s say:

* 2004, Markdown invented
* 2008, GitHub adds Wiki support

Then everything is fine, the list displays as you would expect: bullet point followed by the text.

If however, the number was followed by a full stop:

* 2004. Markdown invented
* 2008. GitHub adds Wiki support

It converts the list to an ordered list (numbers followed by a full stop are interpreted as an ordered list, see section 8.3) and displays the number in roman numerals (again see section 8.3 for details). This is GitHub trying to make sense of the conflicting information we have supplied it.

It’s the full stop after the number that cause the problem, GitHub thinks were trying to create an ordered list starting at 2004, it displays it as roman numerals because it is preceded by an asterisk (see section 8.3.3 for details).

To make the list display properly, we need to escape the full stop (see Table 7.1) by putting a backslash in front of it:

* 2004\. Markdown invented
* 2008\. GitHub adds Wiki support

⬆️ Top

It is possible to add an additional paragraph to an unordered list by indenting it by at least two spaces:

* First point

  Additional paragraph

* Second point
* Third point

<ul>
  <li>First point</li>
  <p>Additional paragraph</p>
  <li>Second point</li>
  <li>Third point</li>
</ul>

The additional paragraph must have a blank line before and after.

⬆️ Top

Unordered lists can contain other Markdown elements such as headings, emphasis (bold, italic, underline &c.) and block quotes. The following shows some examples:

* ### First point

  > Block quote

* *Second point*
* Third point

<ul>
  <li><h3>First point</h3></li>
  <blockquote>
    Block quote
  </blockquote>
  <li><em>Second point</em></li>
  <li>Third point</li>
</ul>

⬆️ Top

⬆️ Top

Ordered or numbered lists are lists that are automatically numbered when rendered by GitHub. They consist of a number followed by a full stop. The number increments for each new line in the list:

1. Point 1
2. Point 2
3. Point 3

Ordered lists are created in Markdown by entering a number followed by a full stop 1. and a space.

Only the first number (top line of the list) matters, this will be the starting number of the list.

The following all work:

1. First point
2. Second point
3. Third point

1. First point
1. Second point
1. Third point

1. First point
4. Second point
6. Third point

1. First point
10. Second point
3. Third point

<ol>
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

In the above table, all the Markdown options produce the same result (a list numbered 1, 2 and 3), this is because the first number in each list is the number 1. The numbers for each subsequent point in a list are calculated automatically by GitHub when it renders the page, the actual numbers in the Markdown text are ignored.

Whichever number you use, it must be the first character on the line (spaces in front of it will be ignored), any non-space character that precedes it will cause the line to render as normal text.

⬆️ Top

7. First point
8. Second point
9. Third point

7. First point
1. Second point
1. Third point

7. First point
4. Second point
6. Third point

7. First point
10. Second point
3. Third point

<ol start="7">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

⬆️ Top

It is possible to nest ordered lists:

1. Level 1 point 1
2. Level 1 point 2 *. Level 2 point 1
   1. Level 2 point 2
      1. Level 3 point 1
3. Level 1 point 3 1 Level 1 point 4

Ordered lists are nested by indenting each list by four spaces before the number for each additional level. The above is generated as follows:

1. Level 1 point 1
1. Level 1 point 2
    1.. Level 2 point 1
    1. Level 2 point 2
        1. Level 3 point 1
1. Level 1 point 3
1 Level 1 point 4

<ol>
  <li>Level 1 point 1</li>
  <li>Level 1 point 2</li>
  <ol>
    <li>Level 2 point 1</li>
    <li>Level 2 point 2</li>
    <ol>
      <li>Level 3 point 1</li>
    </ol>
  </ol>
  <li>Level 1 point 3</li>
  <li>Level 1 point 4</li>
</ol>

Nesting uses different numbering mechanisms for the first three levels: Arabic numerals (1, 2, 3…), lower case Roaman numerals (i, ii, iii…) and lowercase letters (a, b, c…). All subsequent nesting levels use the lowercase letters.

1. Level 1
   1. Level 2
      1. Level 3
         1. Level 4
            1. Level 5

Ordered lists can be indented as far as you like.

⬆️ Top

The type of numbering used in ordered lists is fixed in Markdown: Arabic numerals (1, 2, 3…), lower case Roaman numerals (i, ii, iii…) and lowercase letters (a, b, c…) for all other layers.

HTML allows the type of numbering to be selected (within limits) with the use of the type attribute. The type attribute can specify Arabic numerals type = "1", lowercase alphabetically ordered type = "a", uppercase alphabetically ordered type = "A", lowercase Roman numerals type = "i" or uppercase Roman numerals type = "I".

<ol type = "1">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

<ol type = "a">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

<ol type = "A">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

<ol type = "i">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

<ol type = "I">
  <li>First point</li>
  <li>Second point</li>
  <li>Third point</li>
</ol>

⬆️ Top

In terms of spacing, the number mark is indented two normal spaces and a thin space (see section 7.2) from the left edge of the text area^💠1, the text following the point mark is indented a further single space.

With nested levels, the text of each nested level is indented a further seven normal spaces.

If the line of text following the point wraps at the end of a line, the text will maintain the correct indentation as follows:

1. Point 1
2. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus. Nam ultricies non sapien ac rutrum.
3. Point 3

Here the second point wraps at the end of the line, but maintains the correct indentation.

The full stop following the number is always in the same position from the left-hand edge of the screen.

As more digits are added (going from point 9 to point 10 or from point 99 to point 100 &c.) the left indentation becomes less. This can be seen in the following lists:

Figure 8.1 — Ordered list indentations

In the above diagram the blue dashes show the position of the full stop following the number (these always line up), the black squares start at the left edge of the page (where the body text starts), the orange line shows the left edge of the body text area.

It can be seen that one and two-digit numbers are indented from the left-hand side of the text area, three-digit numbers start at exactly the edge of the text area and any number with more than three digit expands beyond the left edge of the text area (into the margin area).

⬆️ Top

It is possible to add an additional paragraph to an ordered list by indenting it four spaces:

1. First point

    Additional paragraph

1. Second point
1. Third point

<ol>
  <li>First point</li>
  <p>Additional paragraph</p>
  <li>Second point</li>
  <li>Third point</li>
</ol>

The additional paragraph must have a blank line before and after.

⬆️ Top

Ordered lists can contain other Markdown elements such as headings, emphasis (bold, italic, underline &c.) and block quotes. The following shows some examples:

1. ### First point

    > Block quote

1. *Second point*
1. Third point

<ol>
  <li><h3>First point</h3></li>
  <blockquote>
    Block quote
  </blockquote>
  <li><em>Second point</em></li>
  <li>Third point</li>
</ol>

⬆️ Top

⬆️ Top

It is possible to nest together ordered and unordered lists. This usually involves having an unordered list within an ordered list:

1. General Points
    * Max page length
    * Comments
    * Keyboard shortcuts
1. Wiki structures
    * Folder structures
    * Conventions
1. Managing a Wiki
    * Revision control
    * Managing commits

<ol>
  <li>General Points</li>
  <ul>
    <li>Max page length</li>
    <li>Keyboard shortcuts</li>
  </ul>
  <li>Wiki structures</li>
  <ul>
    <li>Folder structures</li>
    <li>Conventions</li>
  </ul>
  <li>Managing a Wiki</li>
  <ul>
    <li>Revision control</li>
    <li>Managing commits</li>
  </ul>
</ol>

They can also be the other way round (unordered list with nested ordered list):

* General Points
    1. Max page length
    1. Comments
    1. Keyboard shortcuts
* Wiki structures
    1. Folder structures
    1. Conventions
* Managing a Wiki
    1. Revision control
    1. Managing commits

<ul>
  <li> General Points </li>
  <ol>
    <li>Max page length</li>
    <li>Keyboard shortcuts</li>
  </ol>
  <li>Wiki structures </li>
  <ol>
    <li>Folder structures</li>
    <li>Conventions</li>
  </ol>
  <li>Managing a Wiki</li>
  <ol>
    <li>Revision control</li>
    <li>Managing commits</li>
  </ol>
</ul>

⬆️ Top

Task lists are a special form of list with checkboxes:

• General Points
• Wiki structures
• Managing a Wik

Task lists are created in Markdown by starting the line with a single dash - followed by a space, followed by an open bracket [ followed by a space followed by a close bracket ] followed by a space: - [ ] .

If the checkbox is to be shown ticked, put an x between the brackets (the x can be lower or uppercase).

The above image is generated with the following Markdown:

- [ ] General Points
- [x] Wiki structures
- [X] Managing a Wik

⬆️ Top

It is possible to nest task lists:

• General Points
  • Max page length
  • Comments
  • Keyboard shortcuts
• Wiki structures
  • Sidebars and Footnotes
  • Folder structures
  • Conventions
    • PracticalSeries
    • Standard
• Managing a Wiki
  • Revision control
  • Managing commits

Task lists are nested by indenting each list by four spaces before the delimiter for each additional level. The above is generated as follows:

- [ ] General Points
    - [ ] Max page length
    - [x] Comments
    - [x] Keyboard shortcuts
- [ ] Wiki structures
    - [ ] Sidebars and Footnotes
    - [x] Folder structures
    - [ ] Conventions
        - [ ] PracticalSeries
        - [x] Standard
- [x] Managing a Wiki
    - [x] Revision control
    - [x] Managing commits

Task lists can be indented as far as you like.

⬆️ Top

Alerts are similar to block quotes (see section 8.1) and are used to highlight specific information. GitHub supports five different types of alert:

Alerts show a different coloured icon for each type and a similarly coloured 4 px wide bar at the left-hand edge of the text.

There is no HTML equivalent for alerts.

The Markdown for the above is:

> [!NOTE]
> Sidenotes and footnotes for reference

> [!TIP]
> Advice or guidance for doing something

> [!IMPORTANT]
> Essential information

> [!WARNING]
> Information for avoiding problems

> [!CAUTION]
> Potential risks associated with specific actions

The Markdown is fairly self-explanatory and is very similar to block quotes.

Alerts begin with a greater than sign followed by a space, an open bracket and an exclamation mark > [!.

It then has one of five words (in either upper or lowercase, it doesn’t matter): NOTE, TIP, IMPORTANT, WARNING or CAUTION (any other word will render the line as a block quote). This is followed by a closing bracket ]. There must be no further text on this line.

Subsequent lines in the alert begin with a greater than sign followed by a space > . If a blank line is needed in the alert, simply start it with a greater than sign > and leave the rest of the line blank.

Alerts use the following colours:

⬆️ Top