---
id: mkdocs-task-collector
version: "0.1.14"
license: unclear
license_treatment: permissive
maintenance: aging
---

# mkdocs-task-collector — A MkDocs plugin to collect TODO, NOTE, and PLACEHOLDER annotations.

License: permissive · Maintenance: aging · Downloads: 195.6K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 195.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs plugin task collection, todo annotation scanner markdown, mkdocs task list generator, collect annotations documentation, markdown todo note placeholder, mkdocs build task tracking, automated documentation task list, mkdocs-plugin, task-tracking, documentation-automation

[View on SkillFed](https://skillfed.io/packages/mkdocs-task-collector) · [View on PyPI](https://pypi.org/project/mkdocs-task-collector/)