# mkdocs-categories-plugin
[](https://pypi.org/project/mkdocs-categories-plugin/) [](https://opensource.org/licenses/MIT)  [](https://pepy.tech/project/mkdocs-categories-plugin)
An MkDocs plugin allowing for categorization of pages in your wiki. This plugin allows for multiple categories per page and will generate a category index page with links to each page within the category.
If you like this MkDocs plugin, you'll probably also like [mkdocs-alias-plugin](https://github.com/EddyLuten/mkdocs-alias-plugin).
## Installation
Using Python 3.10 or greater, install the package using pip:
```zsh
pip install mkdocs-categories-plugin
```
Then add the following entry to the plugins section of your `mkdocs.yml` file:
```yml
plugins:
- categories
```
**Important:** If you already have a directory named `categories` in your project's root directory or a section named `categories`, you must change the `base_name` option to something else in order to prevent issues or data loss.
For further configuration, see the Options section below.
## Usage
Add a `categories` section to your page's meta block:
```yaml
---
categories:
- Novels
- Fiction
- 19th Century Gothic Fiction
---
```
New pages will be generated for each of these categories, with a list of links to each of the wiki pages within the category. Subcategories, links to the parent category, and a link to the "All Categories" page are automatically generated and placed on the page.
Category names are slugified before used in category URLs. For example, `19th Century Gothic Fiction` becomes `19th-century-gothic-fiction`.
Please refer to the [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) for more information on how the meta-data block is used.
### Subcategories
As of version 0.3.0, mkdocs-categories-plugin supports subcategorization. This is achieved by supplying a category name that separates parent from child categories using a separator (by default `|`, configurable via `category_separator`). You may supply as many levels of child categories as you like.
For example:
```yaml
categories:
- Fiction|Romance
- Fiction|Books|British Authors|Female|19th Century
```
The first category definition in this example places the page in the *Romance* subcategory of the *Fiction* parent category. Note that the page will **not** be placed in the parent category of *Fiction*, but only in the *Romance* category. The second category definition places the page in the *19th Century* category, but not in any of its ancestor categories.
## Options
You may customize the plugin by passing options into the plugin's configuration sections in `mkdocs.yml`:
```yaml
plugins:
- categories:
generate_index: true
verbose: false
base_name: 'categories'
section_title: 'Categories'
no_nav: false
category_separator: '|'
```
### `generate_index`
**Default:** `true`
If true, an index page listing all of the generated categories is created at the `base_name` URL.
### `verbose`
**Default:** `false`
You may use the optional `verbose` option to print more information about which categories were defined during build and how many in total.
### `base_name`
**Default:** `categories`
A string used to both serve as the URL base for the category pages as well as the navigation section that's automatically generated. Since this sting is used in the generated category URL, please ensure that it only contains URL friendly characters.
### `section_title`
**Default:** `Categories`
This is the string that's used to render the H2 header at the bottom of each page that defines categories. It is followed by a list of links to each category.
### `no_nav`
**Default:** `false`
By default, mkdocs-categories-plugin will generate navigation entries for each category page under the `base_name` that you provided. If you want to turn this behavior off, set this option to `true`.
There's also a know issue with mkdocs-awesome-pages-plugin compatibility that does not allow you to reorder the position of the generated categories section by using a `.pages` file. If you would rather turn the navigation entries off entirely, this option is for you.
### `category_separator`
**Default:** `|`
This string is used to split the category name in order to define a category hierarchy (see subcategories above).
## Troubleshooting
### There's a directory named `categories` in my project
A fatal error must have occurred during the compilation of your site and left the temporary directory containing the intermediate markdown files used by this plugin behind. It is safe to delete this directory since it's only used during the build.
### `The categories object at URL was not a list, but TYPE`
The page identified did not contain a valid categories configuration object. Please make sure that this is an array of strings.
## Changelog
### 0.4.0
Fixes sorting categories, child pages, etc. containing numbers by using natural sorting from the `natsort` package rather than the default sorting function.
### 0.3.0
Added support for subcategories. Python 3.10 or higher is now required.
### 0.2.1
Patch release: implements a bug fix by @rpmzandwijk reported in [#1](https://github.com/EddyLuten/mkdocs-categories-plugin/issues/1).
### 0.2.0
Introduces support for the automatic generation of category index pages. This new default behavior can be turned off using an option.
### 0.1.1
Fixed a breaking bug caused by passing the wrong data into `sorted`.
### 0.1.0
Initial release with all of the base logic in place.
Raw data
{
"_id": null,
"home_page": "https://github.com/eddyluten/mkdocs-categories-plugin",
"name": "mkdocs-categories-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "mkdocs python markdown category categories link wiki",
"author": "Eddy Luten",
"author_email": "eddyluten@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d2/ad/03195950124d94819fb11b6bd231135ba6f73618b124198bef55b27ceed8/mkdocs-categories-plugin-0.4.0.tar.gz",
"platform": null,
"description": "# mkdocs-categories-plugin\n\n[](https://pypi.org/project/mkdocs-categories-plugin/) [](https://opensource.org/licenses/MIT)  [](https://pepy.tech/project/mkdocs-categories-plugin)\n\nAn MkDocs plugin allowing for categorization of pages in your wiki. This plugin allows for multiple categories per page and will generate a category index page with links to each page within the category.\n\nIf you like this MkDocs plugin, you'll probably also like [mkdocs-alias-plugin](https://github.com/EddyLuten/mkdocs-alias-plugin).\n\n## Installation\n\nUsing Python 3.10 or greater, install the package using pip:\n\n```zsh\npip install mkdocs-categories-plugin\n```\n\nThen add the following entry to the plugins section of your `mkdocs.yml` file:\n\n```yml\nplugins:\n - categories\n```\n\n**Important:** If you already have a directory named `categories` in your project's root directory or a section named `categories`, you must change the `base_name` option to something else in order to prevent issues or data loss.\n\nFor further configuration, see the Options section below.\n\n## Usage\n\nAdd a `categories` section to your page's meta block:\n\n```yaml\n---\ncategories:\n - Novels\n - Fiction\n - 19th Century Gothic Fiction\n---\n```\n\nNew pages will be generated for each of these categories, with a list of links to each of the wiki pages within the category. Subcategories, links to the parent category, and a link to the \"All Categories\" page are automatically generated and placed on the page.\n\nCategory names are slugified before used in category URLs. For example, `19th Century Gothic Fiction` becomes `19th-century-gothic-fiction`.\n\nPlease refer to the [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data) for more information on how the meta-data block is used.\n\n### Subcategories\n\nAs of version 0.3.0, mkdocs-categories-plugin supports subcategorization. This is achieved by supplying a category name that separates parent from child categories using a separator (by default `|`, configurable via `category_separator`). You may supply as many levels of child categories as you like.\n\nFor example:\n\n```yaml\ncategories:\n - Fiction|Romance\n - Fiction|Books|British Authors|Female|19th Century\n```\n\nThe first category definition in this example places the page in the *Romance* subcategory of the *Fiction* parent category. Note that the page will **not** be placed in the parent category of *Fiction*, but only in the *Romance* category. The second category definition places the page in the *19th Century* category, but not in any of its ancestor categories.\n\n## Options\n\nYou may customize the plugin by passing options into the plugin's configuration sections in `mkdocs.yml`:\n\n```yaml\nplugins:\n - categories:\n generate_index: true\n verbose: false\n base_name: 'categories'\n section_title: 'Categories'\n no_nav: false\n category_separator: '|'\n```\n\n### `generate_index`\n\n**Default:** `true`\n\nIf true, an index page listing all of the generated categories is created at the `base_name` URL.\n\n### `verbose`\n\n**Default:** `false`\n\nYou may use the optional `verbose` option to print more information about which categories were defined during build and how many in total.\n\n### `base_name`\n\n**Default:** `categories`\n\nA string used to both serve as the URL base for the category pages as well as the navigation section that's automatically generated. Since this sting is used in the generated category URL, please ensure that it only contains URL friendly characters.\n\n### `section_title`\n\n**Default:** `Categories`\n\nThis is the string that's used to render the H2 header at the bottom of each page that defines categories. It is followed by a list of links to each category.\n\n### `no_nav`\n\n**Default:** `false`\n\nBy default, mkdocs-categories-plugin will generate navigation entries for each category page under the `base_name` that you provided. If you want to turn this behavior off, set this option to `true`.\n\nThere's also a know issue with mkdocs-awesome-pages-plugin compatibility that does not allow you to reorder the position of the generated categories section by using a `.pages` file. If you would rather turn the navigation entries off entirely, this option is for you.\n\n### `category_separator`\n\n**Default:** `|`\n\nThis string is used to split the category name in order to define a category hierarchy (see subcategories above).\n\n## Troubleshooting\n\n### There's a directory named `categories` in my project\n\nA fatal error must have occurred during the compilation of your site and left the temporary directory containing the intermediate markdown files used by this plugin behind. It is safe to delete this directory since it's only used during the build.\n\n### `The categories object at URL was not a list, but TYPE`\n\nThe page identified did not contain a valid categories configuration object. Please make sure that this is an array of strings.\n\n## Changelog\n\n### 0.4.0\n\nFixes sorting categories, child pages, etc. containing numbers by using natural sorting from the `natsort` package rather than the default sorting function.\n\n### 0.3.0\n\nAdded support for subcategories. Python 3.10 or higher is now required.\n\n### 0.2.1\n\nPatch release: implements a bug fix by @rpmzandwijk reported in [#1](https://github.com/EddyLuten/mkdocs-categories-plugin/issues/1).\n\n### 0.2.0\n\nIntroduces support for the automatic generation of category index pages. This new default behavior can be turned off using an option.\n\n### 0.1.1\n\nFixed a breaking bug caused by passing the wrong data into `sorted`.\n\n### 0.1.0\n\nInitial release with all of the base logic in place.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MkDocs plugin allowing for categorization of pages",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/eddyluten/mkdocs-categories-plugin"
},
"split_keywords": [
"mkdocs",
"python",
"markdown",
"category",
"categories",
"link",
"wiki"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5681e878b8487d6fa0b80a590797ad802f1581ef1a3dced142a89e99d8d98c05",
"md5": "ac2b3dc718f0f6e4fd5eb43ac15c9b7c",
"sha256": "dfd8f8cce18af05daff12cd353a3dce40eb4d96a568d452766e843fb5029635e"
},
"downloads": -1,
"filename": "mkdocs_categories_plugin-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac2b3dc718f0f6e4fd5eb43ac15c9b7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8159,
"upload_time": "2023-06-20T05:01:14",
"upload_time_iso_8601": "2023-06-20T05:01:14.891596Z",
"url": "https://files.pythonhosted.org/packages/56/81/e878b8487d6fa0b80a590797ad802f1581ef1a3dced142a89e99d8d98c05/mkdocs_categories_plugin-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d2ad03195950124d94819fb11b6bd231135ba6f73618b124198bef55b27ceed8",
"md5": "1f4f766457b71a01eae635f5516f4948",
"sha256": "b90ee06e63b5539cfa8709e39defb917cc19bbb4816e6479bedfd372f32dc502"
},
"downloads": -1,
"filename": "mkdocs-categories-plugin-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "1f4f766457b71a01eae635f5516f4948",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7839,
"upload_time": "2023-06-20T05:01:16",
"upload_time_iso_8601": "2023-06-20T05:01:16.187466Z",
"url": "https://files.pythonhosted.org/packages/d2/ad/03195950124d94819fb11b6bd231135ba6f73618b124198bef55b27ceed8/mkdocs-categories-plugin-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-20 05:01:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eddyluten",
"github_project": "mkdocs-categories-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-categories-plugin"
}
JSON
