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:

pip install mkdocs-pagelist-plugin

For Github Actions add the following line in the appropriate place in the ci.yml file:

- run: pip install mkdocs-pagelist-plugin

Usage

To use the PageListPlugin, add it to your mkdocs.yml configuration file under the plugins section:

plugins:
  - search
  - pagelist

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:

<div class="pagelist">
    <h3 class="pagelistheading">{folder.capitalize()}</h3>
    <ul class="pagelistlist">
        <li><a href="https://github.com/alanpt/mkdocs-pagelist-plugin/blob/main/./../{page.url}">{page.title}</a></li>
    </ul>
</div>

License

This project is licensed under the MIT License.