Tags are not rendered correctly with snippets extension

SerTetora commented 1 month ago

Context

No response

Bug description

I'm using Snippets extension to include the content of one page into several other. If the included page contains Tags it renders incorrectly on the other pages.

Page 1:

Page 2:

Reproduction

9.5.34-tags-snippets.zip

Steps to reproduce

page1.md contains tags
include page1.md into page2.md using snippets. --8<-- "docs/page1.md"
all other content renders correctly on Page 2 except tags

Browser

Chrome

Before submitting

[X] I have read and followed the bug reporting guidelines.
[X] I have attached links to the documentation, and possibly related issues and discussions.
[X] I assure that I have removed all customizations before submitting this bug report.
[X] I have attached a .zip file with a minimal reproduction using the built-in info plugin.

facelessuser commented 1 month ago

If I had to guess, it is likely that MkDocs Material parsers the frontmatter before Markdown parsing occurs. Snippets is handled in the Markdown processing step.

squidfunk commented 1 month ago

Thanks for reporting!

If I had to guess, it is likely that MkDocs Material parsers the frontmatter before Markdown parsing occurs. Snippets is handled in the Markdown processing step.

That is correct, we extract the tags in on_page_markdown, which we have to do, because we need to generate the tags index which is rendered into another Markdown file. If we would move the tags detection and rendering to a later stage (e.g. on_page_content), we essentially would need to generate HTML, because all pages have been rendered, so the only thing we can still influence is the HTML. The first thing that comes to my mind that will break is the table of contents that is generated as part of the tags index, as the tags generate headline so they can be linked to (a non-linkable tags index make no sense). This handling would now need to be implemented manually, including ensuring that anchors do not clash with existing ids in the HTML.

I'm taking this back to the drawing board with me (we're working in the background, see our latest blog post), and we already have identified tags to be a really hard problem to get right with the limited abilities that MkDocs offers. Withthe current architecture of MkDocs this is not fixable, but we'll see what we can do 🤟

Closing as unfixable with reasonable effort.

squidfunk commented 1 month ago

... however, one other thing that comes to mind: this might also be a bug (or unintended behavior) in Snippets, as it renders the front matter verbatim. MkDocs should actually strip the front matter before passing this to the Markdown parser, so I'm not sure why it is still part of the included page. There should, in fact, be no tags. Oh and a workaround for using tags in pages with snippets is to copy them:

---
tags:
  - Examples
  - Templates
---

--8<-- "docs/page1.md"

facelessuser commented 1 month ago

I doubt this is a bug of Snippets. It reads the file directly that you point it at. Remember, Python Markdown has no concept of documents in a site, it deals with one buffer given to it with no context of your site as a whole.

squidfunk commented 1 month ago

Okay, then it's expected behavior, but kind of counter-intuitive when a Markdown file gets inlined together with front matter and the front matter is then printed verbatim, but yes, Snippets is text-only, so all good.

SerTetora commented 1 month ago

Thank you for the explanation and suggesting a workaround!

In my case, if I don't want to have separate file with common content without tags, I can use the nice feature of snippets in page2.md.

---
tags:
  - Examples
  - Templates
---

--8<-- "docs/page1.md:6"

squidfunk / mkdocs-material