Metadata-Version: 2.1
Name: bettertags
Version: 1.0.0
Summary: mkdocs-material tag plugin with free enhanced versions of some insiders features
Home-page: https://github.com/rzig/bettertags
Author: ryan
Author-email: Ryan Ziegler <ryan@ziegler.lol>
License: Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to
        deal in the Software without restriction, including without limitation the
        rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
        sell copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
        IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/rzig/bettertags
Keywords: mkdocs,insiders,tags,free
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown
Requires-Dist: mkdocs

# Bettertags

`bettertags` is an enhanced version of the [mkdocs-material built-in tags plugin](https://squidfunk.github.io/mkdocs-material/plugins/tags) with FREE improved versions of the following `mkdocs-material` insiders features:

- `tags_extra_files`
- `tags_allowed`

This plugin is originally based on the MIT-licensed source from `mkdocs-material`.

## Installation and usage

1. Run `pip install bettertags`
2. Replace the `tags` configruation option of your `mkdocs.yml` with `bettertags`
3. Add the following to the `plugins` section of `mkdocs.yml`:

```
- tags:
   tags: false
```

So, if your `mkdocs.yml` previously looked like this:

```
site_name: Dr. Everitt's Neighborhood
site_url: https://wiki.hkn.illinois.edu
theme:
  name: material
  palette:
    primary: custom
    accent: custom
    typeset: custom
  features:
    - navigation.tabs
extra_css:
  - styles/theme.css
plugins:
  - search
  - tags:
      tags_file: index.md
```

now it should look like this:

```
site_name: Dr. Everitt's Neighborhood
site_url: https://wiki.hkn.illinois.edu
theme:
  name: material
  palette:
    primary: custom
    accent: custom
    typeset: custom
  features:
    - navigation.tabs
extra_css:
  - styles/theme.css
plugins:
  - search
  - tags:
      tags: false
  - bettertags:
      tags_file: index.md
```

That's it! You can use any of the above insiders features without any additional work.

## `tags_extra_files`

Use this option to add additional tag lists to your wiki:

```
plugins:
  - bettertags:
      tags_extra_files:
        extra-1.md: [allowed-tag-1, allowed-tag-2, ...]
        extra-2.md: "*subfolder"
        extra-3.md: "*"
        "folder/extra-4.md":
            - rule: "*subfolder"
            - priority: 3
```

Each tag index can have one of the following rules:

- `[allowed-tag-1, ...]`: only include tags from the given list
- `*subfolder`: only include tags and pages from files contained within the same parent folder as this index
- `*`: include all tags and pages

An index may also have an associated priority. By default, all extra indices have priority `0`, and the primary index (from `tags_file` option) has priority `1`. When a tag on a wiki page is linked back to a tag index, it is linked to the index with the highest priority that contains the page. By default, this means a tag will always link back to the primary tags index. In the above example, only pages in `folder/` will have tags linking to `folder/extra-4.md`. It is considered _undefined behavior_ to have multiple indices that _tie_ for having the _highest priority_ for a given page/tag pair.

## `allowed_tags`

This works just like the [`allowed-tags`](https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_allowed) option from `mkdocs-material`, I haven't added anything to it.
