[tags plugin] [custom mod] tag_extra_files tags have custom links to their own indexes

[balansczerni]

I've made an extension for tags inspired #3864

Another conceptual thing that needs some thought before this can be tackled: where should tags be linked? If the user clicks on a tag, and this tag is included in two indexes, where should the user be taken? - @squidfunk

First things first: I'm not a programmer.

Description:

If any of tags are assigned to tag_extra_files index, their links to main index are overriden, by a link to their custom index.

Flaws:

You have to be careful not to accidentally put, a tag in two indexes, because the link will be re-written by the last affiliation.

Code

Enable or disable by mkdocs.yml plugins setting:

  - tags:
      tags_extra_files_url: True   

In tags/plugin.py (probably inside your python environment, not mkdocs folder from git*).

    tags_extra_files_url = opt.Type(bool, default = False)

And at the end of the code (between # Add tag URL, if tags index is enabled and # Return tag:

        # If tags_extra_files_url is enabled set tag URL to extra files.
        if self.config.tags_extra_files_url == True:
            for file, included in self.config.tags_extra_files.items():
                    if tag["type"] in included:
                        file = file.replace("index", "").replace(".md", "")
                        tag["url"] = "#".join([
                            file,
                            self.config.tags_slugify(
                                name, self.config.tags_slugify_separator
                        )
                        ])

I didn't do a pull request because:

1. Maybe there is a more elegant solution?
2. It would be nice to set an error message in case the same tag is used in more than one tags_extra_files.

Maybe it will be useful for someone.

I'd love to know what you think.

[squidfunk]

Thanks for suggesting. As you already noticed, there are several cases that render this change problematic, most of which that tags now need to be disjunct between extra files. This is also the reason why we haven't added this functionality yet. A better solution would be to add a little more multi-instance support, allowing the tags plugin to scope to specific pages or sections of your documentation, similar to the include/exclude privacy plugin's settings. Something like:

plugins:
    - tags:
        tags_file: section-a/tags.md
        tags_include:
          - section-a/*
    - tags:
        tags_file: section-b/tags.md
        tags_include:
          - section-b/*

Now, if you would use a tag called "Installation" on any page in section-a, it would link to section-a/tags.md. If you use it in section-b, it links section-b/tags.md. As an additional option, we could introduce the ability to change the tags front matter key, to something else, so you could have multiple tags plugins without conflicts:

plugins:
    - tags:
        tags_key: tags
        tags_file: tags.md
    - tags:
        tags_key: categories
        tags_file: categories.md

You could then use:

---
tags:
  - Foo # links to tags.md#foo
  - Bar # links to tags.md#bar
categories:
  - Foo # links to categories.md#foo
  - Bar # links to categories.md#bar
---

# Headline ...

Both proposals allow for cleaner cutting of tags, while keeping the implementation simple. That would be my proposal to move forward on this topic.