Tags page

[alanpt]

Hello, I am using the insider version. I am using tags_extra_files to create a subset of specific tags, and this works great. What I would like to do is have a tag page that would list the tag contents but grouped by any other tag it may have.

For example these articles named

• "how_to_use_the_callcenter.md" tagged #callcenter and #howto
• "about_the_callcenter.md" tagged #callcenter and #explanation

Using:

 - tags:
     tags_file: tags.md
     tags_extra_files:
       callcentertags.md: 
        - callcenter
extra:
 tags:
   callcenter: callcenter

So the callcentertags.md file would show a list like this:

Callcenter

#howto
how_to_use_the_callcenter.md

#explanation
about_the_callcenter.md

Thanks for any help!

[squidfunk]

Thanks for suggesting. I'm not really sure I understand:

a tag page that would list the tag contents but grouped by any other tag it may have

What do you mean by it? Could you maybe create a full-blown example, so that we can evaluate if it's possible to add this functionality or implement it with things we already have available?

[alanpt]

Hi Squidfunk, I enjoy your work.

Our documents may be tagged by one or more feature, functionality or documentation type (howto, tutorial, explantion, resource).

So when I go to a selected tags_extra_files page for one of those tags, I would like to see all the documents grouped by the other tags those documents may have.

For example this list of documents with the tags:

"how_to_use_the_callcenter.md" tagged #callcenter and #howto
"about_the_callcenter.md" tagged #callcenter and #explanation
"add_users_to_callcenter.md" tagged #callcenter and #howto and #newfeature

When I go to the tag page defined in tags_extra_files called callcentertags.md it would list all the pages with #callcenter but the items are grouped within their other tags.

So the callcentertags.md file would show a list like this:

Callcenter

#howto
how_to_use_the_callcenter.md
add_users_to_the_callcenter.md

#explanation
about_the_callcenter.md

#newfeature
add_users_to_the_callcenter.md

Likewise if we had a tags_extra_file page for #newfeature, we would have all the new features grouped by feature, functionality and document type.

This would make it very easy to automate useful connections. I thought this might be a more mkdocs way of doing things instead of inserting something like this: {{list of pages tagged #tutorial, #callcenter}} - which I would be just as happy being able to do.

I hope that was clearer? This is still a new field to me. Thanks

[squidfunk]

Thanks for the explanation. So if I understand correctly, you want something like a second level tags index, so something like "this page shows all documents that are tagged with #callcenter, but instead of listing all documents in a flat list, groups the documents by the other tags they have, right? If that's the case, you can open a feature request. I've started to rework the tags plugin some time ago, but haven't come around to finish it. This might be useful input, and the more use cases we can resolve, the better.

[alanpt]

Yes, that is correct. I will make it a feature request. I think it would really give Tags a use case for me, which it doesn't at the moment as search and just browsing to the page work perfectly well but this would really up the game by showing cross-article connections.

With your new rework could there be function to be able to add some kind of {{list of pages tagged #tutorial, #callcenter}} or {{list of pages tagged #newfeature}}; And just some way in the footer to have suggestions for other pages that share the same tags?

[squidfunk]

Thanks for creating the feature request.

With your new rework could there be function to be able to add some kind of {{list of pages tagged #tutorial, #callcenter}} or {{list of pages tagged #newfeature}};

Yes, I'm planning to add the ability to inject tags indexes at any point in the documentation.

And just some way in the footer to have suggestions for other pages that share the same tags?

Well, this is also something entirely new. Yes, maybe as well, we'll have to check.

[alanpt]

I don't know if this is helpful or particularly good, but I knocked this up today with some help (ahem chat-gpt). And it covers my needs. I can list pages by tag and group them by folder.

import re
from mkdocs.plugins import BasePlugin
from mkdocs.utils import normalize_url
from urllib.parse import urlsplit

class NavGenerator(BasePlugin):
    # This class defines a MkDocs plugin to generate navigation links based on tags and folders.

    def on_nav(self, nav, config, files):
        # Called when the site navigation is being built.
        self.nav = nav  # The site's navigation object.
        self.files = files  # The list of files in the site.

    def on_post_page(self, output, page, config):
        # Called after a page is rendered.
        # Searches for the {nav ...} pattern in the rendered HTML and replaces it with generated navigation.
        match = re.search(r'\{nav(?:\s+([g])?\s*(.*))?\}', output)
        if match:
            group_folders = match.group(1) == 'g'  # Check if folders should be grouped.
            tags_to_filter = match.group(2).strip().split() if match.group(2) else page.meta.get('tags', [])
            # Extract tags to filter from the match, or use page's own tags if none specified.
            
            filtered_nav = self._format_links_by_folder(tags_to_filter, page, config, group_folders)
            output = output.replace(match.group(0), filtered_nav)
            # Replace the {nav ...} pattern with the generated navigation HTML.

        return output

    def _format_links_by_folder(self, tags_to_filter, current_page, config, group_folders):
        # Generates navigation links grouped by folders.
        folder_groups = {}  # Dictionary to store pages grouped by folder names.
        for file in self.files:
            if file.page is not None and self._page_has_tags(file.page, tags_to_filter):
                folder_name = self._extract_folder_name(file.page.url) if group_folders else ''
                # Extract the folder name if grouping is enabled.
                if folder_name not in folder_groups:
                    folder_groups[folder_name] = []
                folder_groups[folder_name].append(file.page)
                # Group pages by folder name.

        result = '<div class="navtags">'
        for folder, pages in folder_groups.items():
            if group_folders:
                result += f'<h3 class="navtagheading">{folder.capitalize()}</h3>\n' if folder else ''
                # Add a heading for each folder.
            result += '<ul class="navtaglist">\n'
            for page in pages:
                result += f'<li><a href="../../{page.url}">{page.title}</a></li>\n'
                # Generate a list item for each page.
            result += '</ul>\n'
        result += '</div>'

        return result

    def _page_has_tags(self, page, tags_to_filter):
        # Determines if a page has the specified tags.
        if not tags_to_filter:
            return True  # Include all pages if no filter is specified.

        page_tags = set(page.meta.get('tags', []))
        # Split tags into 'any', 'all', and 'exclude' categories.
        any_tags = {tag for tag in tags_to_filter if not tag.startswith('+') and not tag.startswith('-')}
        all_tags = {tag.lstrip('+') for tag in tags_to_filter if tag.startswith('+')}
        exclude_tags = {tag.lstrip('-') for tag in tags_to_filter if tag.startswith('-')}

        # Check for tag matches in each category.
        any_match = any(tag in page_tags for tag in any_tags) if any_tags else True
        all_match = all(tag in page_tags for tag in all_tags)
        exclude_match = not any(tag in page_tags for tag in exclude_tags)

        return any_match and all_match and exclude_match
        # Return True if the page matches the tag criteria.

    def _extract_folder_name(self, url):
        # Extracts the folder name from a page URL.
        path_parts = urlsplit(url).path.strip('/').split('/')
        return path_parts[0].capitalize() if path_parts else 'Root'
        # Capitalize and return the folder name, default to 'Root' if no folder.

[alanpt]

https://github.com/alanpt/mkdocs-tag-navigation-generator

[kamilkrzyskow]

Depending on the amount of files and/or used tags you could be wasting a lot of cycles in for file in self.files: inside _format_links_by_folder.
You could create some dictionary mapping dict[tags, list[page]] inside on_nav for example.
Maybe similarly for the folder_groups, but this seems to rely a bit more on the filtered tags 🤔
For the folder extraction, I guess Path(file.dest_uri).parent would be cleaner.

Also this doesn't need to be a plugin, given the scale it could be a hook as well.
https://www.mkdocs.org/user-guide/configuration/#hooks

Apart of that looks good 👍

[alanpt]

Thanks @kamilkrzyskow ! I added your suggestions and also gave it a filter to only show pages within particular pages and also made a limit to how many can show:

{nav 10 tag1 tag2 -tag3 | folder1 }

Lists 10 pages within folder1 that are tagged tag1 or tag2 as long as they arent tagged with tag3

{nav g tag1}

Lists all pages with tag1 but grouped by the folders they are in.

Just learning about hooks now.