Skip to content

lists.md

Latest commit

 

History

History
332 lines (252 loc) · 5.41 KB

lists.md

File metadata and controls

332 lines (252 loc) · 5.41 KB
Raw

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
    1. Sub-step A
    2. Sub-step B
  2. Second step
    1. Sub-step C
    2. 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
  2. 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"
  1. Second step 
    echo "World"

1. First step
   ``` bash
   echo "Hello"
  1. 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
  • :material-check: Completed feature
  • :material-wrench: Work in progress
  • :material-clock-outline: Planned for next release
  • :material-alert: Needs attention

Lists with links and formatting

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