Table of Contents

Lists

- Markdown lists work.
- Use two-space indent
  - for sublists
  - like this.
  • Markdown lists work.
  • Use two-space indent
    • for sublists
    • like this.
1. Numbered lists work too.
1. Note that Markdown ignores the actual numbers you put in the source code.
1. We thus often mark _all_ the items in a numbered list as `‌1.`‌, so that that the numbering in the source doesn’t become confusingly mismatched with the output when items are added or reordered.
  1. Numbered lists work too.
  2. Note that Markdown ignores the actual numbers you put in the source code.
  3. We thus often mark all the items in a numbered list as 1., so that that the numbering in the source doesn’t become confusingly mismatched with the output when items are added or reordered.
- Note that Markdown draws a distinction between lists _without_ line breaks between items (like the ones above) and lists _with_ breaks between (like this one). In the latter, each list item is a paragraph in the HTML output.

- Coursage’s CSS produces a larger visual gap in the output between list items in this paragraph mode.

- This break-between format also supports multiple paragraphs within a single list item.

  This can work well for long instruction lists. Subsequent paragraphs have to be indented at least two spaces to remain part of the list item and not end the list.

  Note that having the paragraph breaks _anywhere_ inside a list item triggers “list items are paragraphs” mode — and can trigger it for _some but not all_ of the entire list in ways that are visually confusing. It’s thus best practice to use blank lines between _all_ items one list if there are blank lines between / within _any_ of them.

  • Note that Markdown draws a distinction between lists without line breaks between items (like the ones above) and lists with breaks between (like this one). In the latter, each list item is a paragraph in the HTML output.

  • Coursage’s CSS produces a larger visual gap in the output between list items in this paragraph mode.

  • This break-between format also supports multiple paragraphs within a single list item.

    This can work well for long instruction lists. Subsequent paragraphs have to be indented at least two spaces to remain part of the list item and not end the list.

    Note that having the paragraph breaks anywhere inside a list item triggers “list items are paragraphs” mode — and can trigger it for some but not all of the entire list in ways that are visually confusing. It’s thus best practice to use blank lines between all items one list if there are blank lines between / within any of them.

- Paragraph list mode also supports blocks of code:

  `‌`‌`‌
  void foo()
  `‌`‌`‌

  It is _possible_ to use indentation to offset code blocks in a list, but it’s extremely finicky: it is difficult to indent lines enough that Markdown considers them to be code, but not so much that the lines of the code all contain leading spaces. The triple backtick “code fence” is usually easier to wrangle.

  • Paragraph list mode also supports blocks of code:

    void foo()

    It is possible to use indentation to offset code blocks in a list, but it’s extremely finicky: it is difficult to indent lines enough that Markdown considers them to be code, but not so much that the lines of the code all contain leading spaces. The triple backtick “code fence” is usually easier to wrangle.