Return to: MkDocs-MaterialX Start Page

2026-10-192026-10-19

Lists

Lists

MaterialX for MkDocs supports several flavors of lists that cater to different use cases, including unordered lists and ordered lists, which are supported through standard Markdown, as well as definition lists and task lists, which are supported through extensions.

Configuration

Configuration

This configuration enables the use of definition lists and tasks lists, which are both not part of the standard Markdown syntax. Add the following lines to mkdocs.yml:

markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

See additional configuration options:

• Definition Lists
• Tasklist

Usage

Using unordered lists

Using Unordered Lists

Unordered lists can be written by prefixing a line with a -, * or + list marker, all of which can be used interchangeably. Furthermore, all flavors of lists can be nested inside each other:

List, unordered

- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
  accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
  lacinia sed. Aenean in finibus diam.

    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    * Nam vulputate tincidunt fringilla.
    * Nullam dignissim ultrices urna non auctor.

• Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
  accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
  lacinia sed. Aenean in finibus diam.

  • Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
  • Nam vulputate tincidunt fringilla.
  • Nullam dignissim ultrices urna non auctor.

Using Ordered Lists

Using Ordered Lists

Ordered lists must start with a number immediately followed by a dot. The numbers do not need to be consecutive and can be all set to 1., as they will be re-numbered when rendered:

List, ordered

1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.

    1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.

    2.  Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

        1.  Mauris dictum mi lacus
        2.  Ut sit amet placerat ante
        3.  Suspendisse ac eros arcu

1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.

   1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.

   2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

      1. Mauris dictum mi lacus
      2. Ut sit amet placerat ante
      3. Suspendisse ac eros arcu

Using Definition Lists

Using Definition Lists

When Definition Lists is enabled, lists of arbitrary key-value pairs, e.g. the parameters of functions or modules, can be enumerated with a simple syntax:

Definition list

`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.

Using Task Lists

Using Task Lists

When Tasklist is enabled, unordered list items can be prefixed with [ ] to render an unchecked checkbox or [x] to render a checked checkbox, allowing for the definition of task lists:

Task list

- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

• Lorem ipsum dolor sit amet, consectetur adipiscing elit
• Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • In scelerisque nibh non dolor mollis congue sed et metus
  • Praesent sed risus massa
• Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Unordered, Ordered Combinations

1. First ordered list item
2. Another item
   • Unordered sub-list.
3. Actual numbers don't matter, just that it's a number
   1. Ordered sub-list (Will automatically render as i.)
      1. ordered sub-item
      2. ordered sub-item
      3. ordered sub-item
   2. Second ordered sub-item (Will automatically render as ii.)
      1. ordered sub-item
      2. ordered sub-item

4. And another item.

   You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

   To have a line break without a paragraph, you will need to use two trailing spaces.
   Note that this line is separate, but within the same paragraph.
   (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

---

• Unordered list can use asterisks
• Or minuses
• Or pluses

Click to see Code for Lists.

1. First ordered list item
2. Another item
    * Unordered sub-list.
3. Actual numbers don't matter, just that it's a number
    1. Ordered sub-list (Will automatically render as i.)
        1. ordered sub-item
        1. ordered sub-item
        1. ordered sub-item
    2. Second ordered sub-item (Will automatically render as ii.)
        1. ordered sub-item
        1. ordered sub-item
4. And another item.

    You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

    To have a line break without a paragraph, you will need to use two trailing spaces.  
    Note that this line is separate, but within the same paragraph.
    (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

<!-- -->

* Unordered list can use asterisks
- Or minuses
+ Or pluses

Lists.

1. First ordered list item
2. Another item
   • Unordered sub-list.
3. Actual numbers don't matter, just that it's a number
   1. Ordered sub-list (Will automatically render as i.)
      1. ordered sub-item
      2. ordered sub-item
      3. ordered sub-item
   2. Second ordered sub-item (Will automatically render as ii.)
      1. ordered sub-item
      2. ordered sub-item

4. And another item.

   You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

   To have a line break without a paragraph, you will need to use two trailing spaces.
   Note that this line is separate, but within the same paragraph.
   (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

---

• Unordered list can use asterisks
• Or minuses
• Or pluses