Skip to content

Lists

DocsForge supports all standard list types plus extended syntax for task lists, definition lists, and complex nesting.

Unordered lists

Standard Markdown bullet lists:

- Item 1
- Item 2
- Item 3
  • Item 1
  • Item 2
  • Item 3

Nested unordered lists

- Parent item
  - Child item 1
  - Child item 2
    - Grandchild item
- Another parent
  • Parent item
  • Child item 1
  • Child item 2
    • Grandchild item
  • Another parent

Different bullet styles

Use -, *, or + interchangeably:

- Dash item
* Asterisk item
+ Plus item
  • Dash item
  • Asterisk item
  • Plus item

Ordered lists

Standard numbered lists:

1. First item
2. Second item
3. Third item
  1. First item
  2. Second item
  3. Third item

Nested ordered lists

1. First step
   1. Sub-step A
   2. Sub-step B
2. Second step
   1. Sub-step C
   2. Sub-step D
  1. First step
  2. Sub-step A
  3. Sub-step B
  4. Second step
  5. Sub-step C
  6. Sub-step D

Starting from a specific number

5. Fifth item
6. Sixth item
7. Seventh item
  1. Fifth item
  2. Sixth item
  3. Seventh item

Mixed lists

Combine ordered and unordered lists:

1. First step
   - Detail A
   - Detail B
2. Second step
   - Detail C
     1. Sub-detail 1
     2. Sub-detail 2
  1. First step
  • Detail A
  • Detail B
  1. Second step
  • Detail C
    1. Sub-detail 1
    2. Sub-detail 2

Task lists

Enable with pymdownx.tasklist:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
  • Completed task
  • Incomplete task
  • Another task

Nested task lists

- [x] Parent task completed
  - [x] Child task completed
  - [ ] Child task pending
- [ ] Parent task pending
  - [ ] Child task pending
  - [ ] Another child task pending
  • Parent task completed
  • Child task completed
  • Child task pending
  • Parent task pending
  • Child task pending
  • Another child task pending

Task lists with descriptions

- [x] Install DocsForge
  Simple pip install command
- [ ] Create your first page
  Write a `index.md` file
- [ ] Build the site
  Run `docsforge build`
  • Install DocsForge
    Simple pip install command
  • Create your first page
    Write a index.md file
  • Build the site
    Run docsforge build

Fancy task lists (custom styling)

Custom checkbox styling with Material Design is enabled by default:

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

This renders checkboxes with Material Design styling instead of default browser checkboxes.

Definition lists

Enable with def_list:

Term 1
:   Definition of term 1

Term 2
:   Definition of term 2
:   Another definition for term 2
Term 1
Definition of term 1
Term 2
Definition of term 2
Another definition for term 2

Nested definitions

DocsForge
:   A self-contained documentation engine
    :   Vendored dependencies
    :   Zero external downloads
    :   Fast builds

Material Design
:   The design system used by DocsForge
    :   Clean, modern aesthetic
    :   Responsive layouts
DocsForge
A self-contained documentation engine
Vendored dependencies
Zero external downloads
Fast builds
Material Design
The design system used by DocsForge
Clean, modern aesthetic
Responsive layouts

Lists with code blocks

Lists can contain code blocks and other block elements:

1. First step
   ``` bash
   echo "Hello"
   ```
2. Second step
   ``` bash
   echo "World"
   ```
  1. First step
    echo "Hello"
  2. Second step
    echo "World"

Lists with admonitions

- Item with a note
    !!! note
        Important detail about this item
- Another item
    !!! warning
        Be careful with this step
  • Item with a note
    !!! note
    Important detail about this item
  • Another item
    !!! warning
    Be careful with this step

Lists with icons

- :material-check: Completed feature
- :material-wrench: Work in progress
- :material-clock-outline: Planned for next release
- :material-alert: Needs attention
  • Completed feature
  • Work in progress
  • Planned for next release
  • Needs attention
- **Bold item** with *italic* description
- [Link to another page](getting-started.md)
- `inline code` for technical terms
- ==Highlighted text== for emphasis
  • Bold item with italic description
  • Link to another page
  • inline code for technical terms
  • Highlighted text for emphasis

Best practices

  • Use unordered lists for features, options, or unordered items
  • Use ordered lists for sequential steps or ranked items
  • Use task lists for todo lists, checklists, or progress tracking
  • Use definition lists for glossaries, FAQs, or key-value pairs
  • Keep nesting to 3 levels maximum for readability
  • Indent nested items with 2 or 4 spaces consistently
  • Avoid mixing too many element types in one list
  • Use task lists in GitHub issues or project documentation for progress tracking

Next steps