doc:lists [Knowledge Commons]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
//part of the [[start|GtC documentation]]//

====== Lists ======

//Try out all these techniques below in the [[playground:playground]].//

===== Using the toolbar =====

The list icons in the toolbar may not be very easy to see.

{{list-icons.png}}

The one on the left has numbers; the one on the right has dots. The simplest one to use is the one on the right, when\\
`  * Unordered List Item` appears, with the two blank spaces before it. The text is highlighted already, so just type what you want to appear as the item.

A nice feature of the DokuWiki editor is that if you are at the end of a list item line, and press the 'return' key, it gives you the start of a new list item of the same kind at the same level. Press return again if you don't want that, and it goes away, adding blank lines so DokuWiki knows you have finished the list. With no blank line, the text is simply appended to the last list item.

/*
For ordered lists, on a new blank line, pressing the other icon on the left gives `  - Ordered List Item`:
```
  - Ordered List Item
  - another
  - another
```
which gives:
  - Ordered List Item
  - another
  - another



Make sure you do **not** have a blank line before the ordered list starts. If you do, it interprets it following Markdown syntax.
*/

For the time being, the only ordered list method that works is using Markdown syntax.



===== DokuWiki syntax =====

==== Unordered lists ====
If you want to edit directly, without the toolbar, this:
```
  * unordered List Item
  * two spaces before is the norm for DokuWiki list items
    * a sub-item
    * and another sub-item
      * sub-sub-item
```

gives you this, in proper DokuWiki style:
  * unordered List Item  
  * two spaces before is the norm for DokuWiki list items
    * a sub-item
    * and another sub-item
      * sub-sub-item

If you don't follow these rules, you may get something like this, thanks to the Markdown plugin:

```
* no blank spaces
 - just one blank space before this
  * would be a normal unordered list item
   - what is this then?
```

producing:

* no blank spaces
 - just one blank space before this
  * would be a normal unordered list item
   - what is this then?

==== Ordered lists ====
FIXME: ordered lists currently don't work with DokuWiki syntax, because it is overridden by Markdown syntax.
```
To get ordered lists to work with DokuWiki syntax:
  - You must **not** have a blank line before the list
  - But you must ensure that there are two spaces before the `-` mark
  - There's nothing intuitive about using `-` for ordered lists
    - just enter a space for the next list item, and it will become a sub-list
    - and backspace to get you back up
  - But don't forget to put a blank line at the end.
```

To get ordered lists to work with DokuWiki syntax:
  - You must **not** have a blank line before the list
  - But you must ensure that there are two spaces before the `-` mark
  - There's nothing intuitive about using `-` for ordered lists
    - just enter a space for the next list item, and it will become a sub-list
    - and backspace to get you back up
  - But don't forget to put a blank line at the end.


===== Markdown syntax =====

Markdown syntax does work for lists, and for our wiki it is fine to use it. It seems more intuitive than DokuWiki syntax in this case. But you can't get it from the toolbar.

For an unordered (bulleted) list in Markdown, just start a line with `-` or `*`. Indent, as shown above, to create sub-items. Another **very important point** for Markdown list to work, they need a blank link before them.

For ordered (numbered) lists, you can use numbers and no spaces on the left — this comes out exactly as expected:
```
1. the first point
2. the second point
```

1. the first point
2. the second point

The interesting quirk of Markdown list syntax is that the numbers you use are ignored for the display, except the first number in the list. Look what happens when you type this:

```
2. now, if you put the first point as '2' it is displayed as '2'
1. but if you go backwards, the display moves forward
  1. indent, and you get a sub-list, probably with letters instead of numbers
10. and even if you use two-digit numbers, they are just more numbers.
```

2. now, if you put the first point as '2' it is displayed as '2'
1. but if you go backwards, the display moves forward
  1. indent, and you get a sub-list, probably with letters instead of numbers
10. and even if you use two-digit numbers, they are just more numbers.

===== MediaWiki =====

See [[MediaWiki and DokuWiki]]; For Markdown, use indenting instead of piling up like `***`, and use actual numbers with a period `5.` instead of `#`, with indentation instead of piling up `###`.