Tags not working as expected

[kikinovak]

Hi,

I'm currently migrating my website and my blog to MkDocs Material. Since is my first post here, kudos to the developers for their great work!

So far things look great. I have one small detail that I can't seem to figure out. I have my site and my blog merged, and I'd like to use tags for the blog. I activated the tags plugin in mkdocs.yml and added a few tags to a couple pages.

Here's an example:

https://kikinovak.gitlab.io/microlinux/blog/apprendre-un-metier/

And here's another example:

https://kikinovak.gitlab.io/microlinux/blog/qualiopi/

1. The expected behavior is for me to be able to click on a tag and then I see a list of articles that sport the same tag. Unfortunately the tags are not clickable, and nothing happens.

2. It would be nice if there was a possibility to display the list of tags at the bottom of a page and not at the top.

Any suggestions ?

Cheers from the sunny South of France,

Niki

[kikinovak]

I have found a solution that somehow works, but I'm puzzled. After a couple hours of experimenting with all possible permutations, here's what I came up with:

nav:
  - Accueil: index.md
  - Infogérance:
      - Poste de travail Linux: poste-de-travail-linux.md
  - Formations:
      - Formation Linux: formation-linux.md
  - Blog:
      - blog/index.md
      - blog/tags.md
...
plugins:
  - blog:
      categories_allowed:
        - Bureaucratie
        - Formation
      post_url_format: "{slug}"
  - glightbox
  - search
  - tags:
      tags_file: blog/tags.md

I created a docs/blog/tags.md file with the following content:

---
icon: material/tag-search-outline
---

Navigation par mots-clés
========================

And now things work. Well, I get the following warning when launching mkdocs serve:

WARNING -  Config value 'plugins': Plugin 'material/tags' option 'tags_file': This setting is not required
           anymore

Except when I remove the tags_file option, the content of my tags page disappears.

Any suggestions ?

[kamilkrzyskow]

Hi @kikinovak,
before version 9.6.0 the tags plugin use another logic, where the user defined the file path to the index page for the tags, and then the plugin would use that file and add the index to it.

1. User defines tags_file: blog/tags.md and optionally the location of the index in that file with a marker
2. Tags plugin uses the provided path and adds the index in place of the marker or adds a new marker at the end of the file

Now since 9.6.0 a new tags plugin was implemented, and the logic was "reversed" or simplified for user experience.

1. User does not have to define a single index file, instead the user adds a placeholder marker in any file they want.
2. Tags plugin finds the placeholder marker and adds the index there.

The old logic still works for now, for backwards compatibility, and it will probably work forever since 9.7.0 is the last version, but the warning is still there, as it's not the recommended approach.

So instead add the placeholder marker in any file: <!-- material/tags -->

Source code for the current tags_file fallback:

mkdocs-material/material/plugins/tags/plugin.py

Lines 258 to 274 in 7f32877

	directive = self.config.listings_directive
	if page.file.src_uri != self.config.tags_file:
	return markdown
	# Try to find the legacy tags marker and replace with directive
	if "[TAGS]" in markdown:
	markdown = markdown.replace(
	"[TAGS]", f"<!-- {directive} -->"
	)
	# Try to find the directive and add it if not present
	pattern = r"<!--\s+{directive}".format(directive = directive)
	if not re.search(pattern, markdown):
	markdown += f"\n<!-- {directive} -->"
	# Return markdown
	return markdown

Docs: https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#adding-a-tags-index
Example on Nype website, (source)

[kikinovak]

Thank you very much for your detailed explanation ! I changed my code accordingly, and everything works perfectly now.