mkdocs-material/docs/reference/lists.md

template
overrides/main.html

Lists

Material 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

Definition List

:octicons-file-code-24: Source · :octicons-workflow-24: Extension

The Definition List extension, which is part of the standard Markdown library, adds the ability to add definitions lists to a document and can be enabled via mkdocs.yml:

markdown_extensions:
  - def_list

Tasklist

:octicons-file-code-24: Source · :octicons-workflow-24: Extension

The Tasklist extension, which is part of Python Markdown Extensions, adds support for lists with styled checkboxes, and provides several options for configuring the style:

custom_checkbox{ #custom-checkbox }

:octicons-milestone-24: Default: false · This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, and is therefore strongly recommended:

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

clickable_checkbox{ #clickable-checkbox }

:octicons-milestone-24: Default: false · This option toggles whether checkboxes are clickable. As the state is not persisted, the use of this option is rather discouraged from a user experience perspective:

markdown_extensions:
  - pymdownx.tasklist:
      clickable_checkbox: true

Usage

Using unordered lists

An unordered list 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.

Example:

- 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.

Result:

• 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

An ordered list 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.

Example:

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

Result:

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

Definition lists are a ideal for describing arbitrary key-value pairs, e.g. the parameters of functions or modules, as used within this documentation to describe extension or plugin parameters.

Example:

`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.

Result:

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 tasklists

When the Tasklist extension is enabled, unordered list items can be prefixed with [ ] to render an unchecked or [x] to render a checked checkbox.

Example:

- [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

Result:

• 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