Using blocks or custom fences to transform Markdown to Markdown?

[squidfunk]

I'm currently working on the next iteration of the tags plugin. We want to make usage of tags indexes much more flexible and declarative, allowing the author to define inline tags indexes with YAML configuration which we then validate in the plugin. I've read the block and superfences docs, and don't think this is possible, but I wanted to ask nonetheless. Essentially, I need to read and transform a configuration provided by the author to a placeholder anchor that the plugin later will replace with the tags index.

The syntax could be something like:

Create a scoped tags index (only for the current subtree) that includes pages tagged with foo and bar:

/// tags.listing
    scope: true
    include:
      - foo
      - bar
///

Create a tags index with the configuration named "foo" as defined in mkdocs.yml:

/// tags.listing | foo
///

For each of those listings, I need to produce something like:

###### $unique-id

This will later be replaced with the tags index. My current solution is to use a custom syntax like <!-- @tags ... -->, but that is clearly not the best solution, as it would be amazing if we could resort to established syntax. As I've written, I'm not seeing how this can be done with a Markdown extension, but I wanted to ask you, @facelessuser, as you've written quite some of them ☺️

[facelessuser]

We could definitely output ###### $unique-id with the below, but I don't think we currently allow . in the name, maybe we could relax that.

/// tags.listing | foo
///

I'm not sure what you want to do with below, what is its output? Is this just the signature of the blocks' options? Or you declare this once on a page, and then use the above?

/// tags.listing
    scope: true
    include:
      - foo
      - bar
///

[squidfunk]

The output should be a H6 headline with a unique ID, which is then picked up by the toc extension:

###### $unique-id

[squidfunk]

Maybe it's easier to explain by an example, see squidfunk/mkdocs-material#6517 (comment)

[facelessuser]

I'm probably most interested in a spec, understanding desired input and output. How it is used in Material is possibly less important than understanding exactly what is required of the extension, though probably useful for context.

I think what you want is possible, you just need to control the output. If . is absolutely needed in the name, we would probably have to relax the syntax. Also, is the extension generating the unique ID? How unique? Unique according to some constraint? Or completely unique and random to the whole page?

Keep in mind, I haven't leveraged tags before now, so I am unfamiliar with how tags operate in Material. Basically, I think almost anything is possible, but having a clear spec will make it easy for me to say yes or no. I and try and look over the comment and such and see if that gives me a clear picture.

[squidfunk]

Okay, I guess this cannot be answered with a quick yes or no ☺️ Let me finish the first draft of the new extension using the HTML comment syntax, and then I'll get back to you with more details and examples to discuss whether this can be implemented with a fence or block, and whether this makes sense in the first place.