# PageListPlugin for MkDocs
PageListPlugin is a plugin for MkDocs that dynamically generates lists of pages based on tags, folders, and other criteria directly within your markdown files. It's especially useful for creating dynamic references to other parts of your documentation based on shared tags or directory structure. It may need tweaking for your needs. The use of grouping by folders is helpful if you use the Diátaxis framework to organise your documents. I have all my documents listed under the folders - Tutorials, How-to, Reference,
Explanation. Tags are used to cross connect across those folders with features, functions or intended audience.
## Installation
To install the plugin, use the following command:
```bash
pip install mkdocs-pagelist-plugin
```
## Usage
To use the PageListPlugin, add it to your `mkdocs.yml` configuration file under the plugins section:
```yaml
plugins:
- search
- mkdocs-pagelist-plugin
```
> **Note**: If you have no `plugins` entry in your config file yet, you'll need to add it before adding PageListPlugin, as MkDocs enables only the `search` plugin by default.
## Examples
- **List other pages sharing the same tags as the current page**:
```
{pagelist}
```
- **List 10 pages sharing the same tags as the current page**:
```
{pagelist 10}
```
- **Group pages by folder, sharing the same tags as the current page**:
```
{pagelist g}
```
- **List pages tagged with 'draft'**:
```
{pagelist 5 draft}
```
- **Combine multiple tags ('draft' and 'leads')**:
```
{pagelist 10 draft leads}
```
- **Include pages with 'leads' tag but exclude those with 'draft' tag**:
```
{pagelist 10 -draft leads}
```
- **Group pages by folder, tagged with 'leads'**:
```
{pagelist g leads}
```
- **Group pages by folder, tagged with 'leads' but not 'draft'**:
```
{pagelist g leads -draft}
```
- **List pages tagged with 'leads' in the 'how-to' folder**:
```
{pagelist 10 leads | how-to}
```
- **Generate a report of all `{pagelist}` commands used across the site**:
```
{pagelist i}
```
## HTML and CSS
The rendered code looks something like this:
```html
<div class="pagelist">
<h3 class="pagelistheading">{folder.capitalize()}</h3>
<ul class="pagelistlist">
<li><a href="../../{page.url}">{page.title}</a></li>
</ul>
</div>
```
## License
This project is licensed under the MIT License.
---
Raw data
{
"_id": null,
"home_page": "https://github.com/alanpt/mkdocs-pagelist-plugin",
"name": "mkdocs-pagelist-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "mkdocs python markdown pagelist",
"author": "Alan Proctor-Thomson",
"author_email": "alanpt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/be/f34c5225f80868a60a9ec522a51fc1d9fc0a6f10ebf84524f0fa40a1c4ee/mkdocs-pagelist-plugin-0.1.1.tar.gz",
"platform": null,
"description": "# PageListPlugin for MkDocs\r\n\r\nPageListPlugin is a plugin for MkDocs that dynamically generates lists of pages based on tags, folders, and other criteria directly within your markdown files. It's especially useful for creating dynamic references to other parts of your documentation based on shared tags or directory structure. It may need tweaking for your needs. The use of grouping by folders is helpful if you use the Di\u00c3\u00a1taxis framework to organise your documents. I have all my documents listed under the folders - Tutorials, How-to, Reference, \r\nExplanation. Tags are used to cross connect across those folders with features, functions or intended audience. \r\n\r\n## Installation\r\n\r\nTo install the plugin, use the following command:\r\n\r\n```bash\r\npip install mkdocs-pagelist-plugin\r\n```\r\n\r\n## Usage\r\n\r\nTo use the PageListPlugin, add it to your `mkdocs.yml` configuration file under the plugins section:\r\n\r\n```yaml\r\nplugins:\r\n - search\r\n - mkdocs-pagelist-plugin\r\n```\r\n\r\n> **Note**: If you have no `plugins` entry in your config file yet, you'll need to add it before adding PageListPlugin, as MkDocs enables only the `search` plugin by default.\r\n\r\n## Examples\r\n\r\n- **List other pages sharing the same tags as the current page**:\r\n ```\r\n {pagelist}\r\n ```\r\n\r\n- **List 10 pages sharing the same tags as the current page**:\r\n ```\r\n {pagelist 10}\r\n ```\r\n\r\n- **Group pages by folder, sharing the same tags as the current page**:\r\n ```\r\n {pagelist g}\r\n ```\r\n\r\n- **List pages tagged with 'draft'**:\r\n ```\r\n {pagelist 5 draft}\r\n ```\r\n\r\n- **Combine multiple tags ('draft' and 'leads')**:\r\n ```\r\n {pagelist 10 draft leads}\r\n ```\r\n\r\n- **Include pages with 'leads' tag but exclude those with 'draft' tag**:\r\n ```\r\n {pagelist 10 -draft leads}\r\n ```\r\n\r\n- **Group pages by folder, tagged with 'leads'**:\r\n ```\r\n {pagelist g leads}\r\n ```\r\n\r\n- **Group pages by folder, tagged with 'leads' but not 'draft'**:\r\n ```\r\n {pagelist g leads -draft}\r\n ```\r\n\r\n- **List pages tagged with 'leads' in the 'how-to' folder**:\r\n ```\r\n {pagelist 10 leads | how-to}\r\n ```\r\n\r\n- **Generate a report of all `{pagelist}` commands used across the site**:\r\n ```\r\n {pagelist i}\r\n ```\r\n\r\n## HTML and CSS\r\n\r\nThe rendered code looks something like this:\r\n\r\n```html\r\n<div class=\"pagelist\">\r\n\t<h3 class=\"pagelistheading\">{folder.capitalize()}</h3>\r\n\t<ul class=\"pagelistlist\">\r\n\t\t<li><a href=\"../../{page.url}\">{page.title}</a></li>\r\n\t</ul>\r\n</div>\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin to list pages based on tags and folders",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/alanpt/mkdocs-pagelist-plugin"
},
"split_keywords": [
"mkdocs",
"python",
"markdown",
"pagelist"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96104732fc0fc0e53da6f6a3d9b324a47ed4be75c25419b9f3a1e1accffd1463",
"md5": "812162a3dd4fddc831653793d09cf116",
"sha256": "1185ec7d360522da5b52da53c0d0705e656eb5ca7e2abf2ed0c5b04a78845ec5"
},
"downloads": -1,
"filename": "mkdocs_pagelist_plugin-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "812162a3dd4fddc831653793d09cf116",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 4412,
"upload_time": "2023-12-13T00:18:09",
"upload_time_iso_8601": "2023-12-13T00:18:09.509408Z",
"url": "https://files.pythonhosted.org/packages/96/10/4732fc0fc0e53da6f6a3d9b324a47ed4be75c25419b9f3a1e1accffd1463/mkdocs_pagelist_plugin-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0fbef34c5225f80868a60a9ec522a51fc1d9fc0a6f10ebf84524f0fa40a1c4ee",
"md5": "99ab1594ab96de201599800e201c48d1",
"sha256": "b06d566fb8de6440dc1eb090c4fb002be13260a5017f1b32541428db36cb5fc8"
},
"downloads": -1,
"filename": "mkdocs-pagelist-plugin-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "99ab1594ab96de201599800e201c48d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3921,
"upload_time": "2023-12-13T00:18:11",
"upload_time_iso_8601": "2023-12-13T00:18:11.270176Z",
"url": "https://files.pythonhosted.org/packages/0f/be/f34c5225f80868a60a9ec522a51fc1d9fc0a6f10ebf84524f0fa40a1c4ee/mkdocs-pagelist-plugin-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-13 00:18:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alanpt",
"github_project": "mkdocs-pagelist-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-pagelist-plugin"
}
JSON
