mkdocs-task-collector

What it is and what it does

mkdocs-task-collector is a MkDocs plugin that automatically extracts TODO, NOTE, and PLACEHOLDER annotations from your Markdown documentation and generates a consolidated task list. It runs during the MkDocs build process with zero configuration beyond adding it to your mkdocs.yml file, making it useful for tracking documentation work-in-progress items alongside your site.

The plugin scans all Markdown files, collects matching annotations with their source file and line number, and writes them to a configurable output file (typically tasks-list.md). The generated file can be included in your documentation navigation and is automatically updated on each build, both locally and in remote deployment environments like GitHub Pages.

Use it for:

• Track TODO items embedded in documentation that need completion before publishing
• Maintain a centralized NOTE list across multiple documentation files for review
• Collect PLACEHOLDER markers indicating where diagrams, examples, or content should be inserted
• Audit documentation work-in-progress during the build process without manual scanning
• Generate a living task dashboard published alongside your documentation site

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that scans Markdown files for TODO, NOTE, and PLACEHOLDER annotations and automatically generates an organized task list.

Yes, if you use MkDocs and want to track embedded annotations automatically. The plugin is straightforward to set up, has no configuration overhead, and solves a real documentation-management problem. However, note that maintenance is aging (last release over a year ago), so consider whether you're comfortable with a package that may not receive rapid updates. No known vulnerabilities and permissive licensing make it low-risk to try.

Install

mkdocs-task-collector on PyPI

pip install mkdocs-task-collector

uv add mkdocs-task-collector

poetry add mkdocs-task-collector

Installing mkdocs-task-collector

Before you install

Low install friction with a single runtime dependency on mkdocs. Maintenance status is aging—last release was over a year ago (2024-08-11), though the repository remains active with a recent commit (2025-06-08) and no archived status.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart

pip install mkdocs-task-collector

Add to mkdocs.yml:
plugins:
  - task_collector:
      output_file: 'tasks-list.md'

Add to nav section:
nav:
  - Tasks: tasks-list.md

Run: mkdocs build

Verify before relying

• Whether the plugin correctly handles edge cases like quoted annotations (e.g., ``TODO``) as mentioned in the roadmap
• Whether generated task list links are clickable and point to specific files/lines, or if this remains a planned feature

Package facts

Evidence: mkdocs_task_collector-0.1.14-py3-none-any.whl

Keywords: mkdocs, plugin, task, todo, note, placeholder

Tags

More Documentation packages