# mkdocs-task-collector
`mkdocs-task-collector` is a versatile MkDocs plugin designed to streamline your documentation workflow by automatically scanning your Markdown files for specific annotations like `TODO`, `NOTE`, and `PLACEHOLDER`. It generates a comprehensive and organized task list, making it easier to manage and track tasks, notes, and placeholders within your documentation.
## Roadmap
TODO: tags should not be collected if wrapped in quotes (e.g., ``TODO``), because usualy this is what we do when we describe the tags (and not use them).
TODO: make links in the Task list clickable (specific files, possibly lines?)
## Features
- **Automated Annotation Scanning**: Effortlessly detects `TODO`, `NOTE`, and `PLACEHOLDER` annotations in your Markdown files, saving you time and ensuring no task is overlooked.
- **Consolidated Task List**: Automatically creates a structured task list in a Markdown file, organized by the source file and line number, providing a clear overview of all annotations.
- **Seamless Integration**: Integrates flawlessly into the MkDocs build process, both locally and remotely (e.g., GitHub Pages), without requiring additional configuration.
- **Automatic Deployment**: Ensures that your task list is always up-to-date and published on your website, provided it is referenced in the `nav` section of your `mkdocs.yml` file.
- **Zero Configuration**: No extra configuration needed – simply add the plugin to your `mkdocs.yml` file, and you're ready to go.
## Installation
Install the plugin using `pip`:
```
pip install mkdocs-task-collector
```
## Configuration
Add the `task_collector` plugin to your `mkdocs.yml` configuration file:
```
plugins:
- search
- task_collector:
output_file: 'tasks-list.md'
```
To ensure the generated task list is part of your documentation navigation, add it to the `nav` section in your `mkdocs.yml` file:
```
nav:
Home: index.md
Tasks: tasks-list.md
```
## Usage
When you build your MkDocs site, the plugin will scan for `TODO`, `NOTE`, and `PLACEHOLDER` annotations and generate a `tasks-list.md` file in your documentation.
### Example
Suppose you have the following Markdown files:
**`docs/example1.md`**:
```
# Example 1
This is a test document.
TODO: Add more content here.
NOTE: Review this section for accuracy.
```
**`docs/example2.md`**:
```
# Example 2
PLACEHOLDER: Insert diagram here.
TODO: Update the introduction.
```
After running `mkdocs build`, the plugin will generate a `tasks-list.md` with the following content:
```
# Task List
## example1.md
+ Line 5 - **TODO**: Add more content here.
+ Line 7 - **NOTE**: Review this section for accuracy.
## example2.md
+ Line 5 - **PLACEHOLDER**: Insert diagram here.
+ Line 7 - **TODO**: Update the introduction.
```
## Additional Information
### Task List File Management
- **Generation**: The `tasks-list.md` file is generated during the build process.
- **Saving**: This file is saved into the `docs` folder if the generated file is different from the existing local file or if the local file is not found.
### Deployment Considerations
- **Local Deployments**: The `tasks-list.md` file is required for local deployments to ensure it is part of the built site.
- **Remote Deployments (e.g., GitHub Pages)**:
- If you are using GitHub Pages or similar solutions for automatic deployment (where the website is built remotely), add `tasks-list.md` to your `.gitignore` file.
- This ensures that if no task list is present in the main branch of the repository, the file will be generated in the deployed environment every time the site is built from the MkDocs documentation. Thus, a page for this file will be created in the documentation if it is correctly specified in the `nav` section of the `mkdocs.yml` file.
### Example `.gitignore` Entry
Add the following line to your `.gitignore` to exclude `tasks-list.md`:
```
docs/tasks-list.md
```
## Contributing
Contributions are welcome! Please submit a pull request or open an issue to discuss changes.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/costantinoai/mkdocs-task-collector",
"name": "mkdocs-task-collector",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "mkdocs plugin task todo note placeholder",
"author": "Andrea Costantino",
"author_email": "andreaivancostantino@outlook.it",
"download_url": "https://files.pythonhosted.org/packages/90/f8/51340961b8ebc1bd34609d12b0e5ea180f5ccc294971ce1ef2a873025284/mkdocs_task_collector-0.1.14.tar.gz",
"platform": null,
"description": "# mkdocs-task-collector\n\n`mkdocs-task-collector` is a versatile MkDocs plugin designed to streamline your documentation workflow by automatically scanning your Markdown files for specific annotations like `TODO`, `NOTE`, and `PLACEHOLDER`. It generates a comprehensive and organized task list, making it easier to manage and track tasks, notes, and placeholders within your documentation.\n\n\n\n## Roadmap\n\nTODO: tags should not be collected if wrapped in quotes (e.g., ``TODO``), because usualy this is what we do when we describe the tags (and not use them).\nTODO: make links in the Task list clickable (specific files, possibly lines?)\n\n## Features\n\n- **Automated Annotation Scanning**: Effortlessly detects `TODO`, `NOTE`, and `PLACEHOLDER` annotations in your Markdown files, saving you time and ensuring no task is overlooked.\n- **Consolidated Task List**: Automatically creates a structured task list in a Markdown file, organized by the source file and line number, providing a clear overview of all annotations.\n- **Seamless Integration**: Integrates flawlessly into the MkDocs build process, both locally and remotely (e.g., GitHub Pages), without requiring additional configuration.\n- **Automatic Deployment**: Ensures that your task list is always up-to-date and published on your website, provided it is referenced in the `nav` section of your `mkdocs.yml` file.\n- **Zero Configuration**: No extra configuration needed \u2013 simply add the plugin to your `mkdocs.yml` file, and you're ready to go.\n\n## Installation\n\nInstall the plugin using `pip`:\n\n```\npip install mkdocs-task-collector\n```\n\n## Configuration\n\nAdd the `task_collector` plugin to your `mkdocs.yml` configuration file:\n\n```\nplugins:\n - search\n - task_collector:\n output_file: 'tasks-list.md'\n```\n\nTo ensure the generated task list is part of your documentation navigation, add it to the `nav` section in your `mkdocs.yml` file:\n\n```\nnav:\n\n Home: index.md\n Tasks: tasks-list.md\n```\n\n## Usage\n\nWhen you build your MkDocs site, the plugin will scan for `TODO`, `NOTE`, and `PLACEHOLDER` annotations and generate a `tasks-list.md` file in your documentation.\n\n### Example\n\nSuppose you have the following Markdown files:\n\n**`docs/example1.md`**:\n\n```\n# Example 1\n\nThis is a test document.\n\nTODO: Add more content here.\n\nNOTE: Review this section for accuracy.\n```\n\n**`docs/example2.md`**:\n\n```\n# Example 2\n\nPLACEHOLDER: Insert diagram here.\n\nTODO: Update the introduction.\n```\n\nAfter running `mkdocs build`, the plugin will generate a `tasks-list.md` with the following content:\n\n```\n# Task List\n\n## example1.md\n+ Line 5 - **TODO**: Add more content here.\n+ Line 7 - **NOTE**: Review this section for accuracy.\n\n## example2.md\n+ Line 5 - **PLACEHOLDER**: Insert diagram here.\n+ Line 7 - **TODO**: Update the introduction.\n```\n\n## Additional Information\n\n### Task List File Management\n\n- **Generation**: The `tasks-list.md` file is generated during the build process.\n- **Saving**: This file is saved into the `docs` folder if the generated file is different from the existing local file or if the local file is not found.\n\n### Deployment Considerations\n\n- **Local Deployments**: The `tasks-list.md` file is required for local deployments to ensure it is part of the built site.\n- **Remote Deployments (e.g., GitHub Pages)**:\n - If you are using GitHub Pages or similar solutions for automatic deployment (where the website is built remotely), add `tasks-list.md` to your `.gitignore` file.\n - This ensures that if no task list is present in the main branch of the repository, the file will be generated in the deployed environment every time the site is built from the MkDocs documentation. Thus, a page for this file will be created in the documentation if it is correctly specified in the `nav` section of the `mkdocs.yml` file.\n\n### Example `.gitignore` Entry\n\nAdd the following line to your `.gitignore` to exclude `tasks-list.md`:\n\n```\ndocs/tasks-list.md\n```\n\n## Contributing\n\nContributions are welcome! Please submit a pull request or open an issue to discuss changes.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A MkDocs plugin to collect TODO, NOTE, and PLACEHOLDER annotations.",
"version": "0.1.14",
"project_urls": {
"Bug Reports": "https://github.com/costantinoai/mkdocs-task-collector/issues",
"Homepage": "https://github.com/costantinoai/mkdocs-task-collector",
"Source": "https://github.com/costantinoai/mkdocs-task-collector"
},
"split_keywords": [
"mkdocs",
"plugin",
"task",
"todo",
"note",
"placeholder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3941dc924273eca670b1bb3008ad17cbd781e62e1e05427ea51229d226efe3aa",
"md5": "45e6018252f6ce7e6cc414b850ba1abd",
"sha256": "f3d75f1d0e69ba31e3c2fc1baafc80f9f833bad4fa25045d8639086604339a7c"
},
"downloads": -1,
"filename": "mkdocs_task_collector-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45e6018252f6ce7e6cc414b850ba1abd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6182,
"upload_time": "2024-08-11T21:24:20",
"upload_time_iso_8601": "2024-08-11T21:24:20.764584Z",
"url": "https://files.pythonhosted.org/packages/39/41/dc924273eca670b1bb3008ad17cbd781e62e1e05427ea51229d226efe3aa/mkdocs_task_collector-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "90f851340961b8ebc1bd34609d12b0e5ea180f5ccc294971ce1ef2a873025284",
"md5": "a1892cac01a10266bc5503362caaf6e5",
"sha256": "c37088ce27b2ed6cfe31d9817b42909a1077b2397a66a0a973cabc73f7ab0605"
},
"downloads": -1,
"filename": "mkdocs_task_collector-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "a1892cac01a10266bc5503362caaf6e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5715,
"upload_time": "2024-08-11T21:24:22",
"upload_time_iso_8601": "2024-08-11T21:24:22.395920Z",
"url": "https://files.pythonhosted.org/packages/90/f8/51340961b8ebc1bd34609d12b0e5ea180f5ccc294971ce1ef2a873025284/mkdocs_task_collector-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-11 21:24:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "costantinoai",
"github_project": "mkdocs-task-collector",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-task-collector"
}
JSON
