Alternate block header syntax

[robinlioret]

Address #2491

I'm facing the same issue with VSCode auto formatter. It's forcing me to disable formatOnSave, which is not a thing I want.

This PR adds an alternative syntax to the way blocks' attributes header are processed.

It is:

• Completely retrocompatible, so existing project don't have to modify anything.
• Simple yet unlikely to be a content

Per example:

/// admonition | Some title
@type: warning

Some content
///

[facelessuser]

I appreciate the PR, but I'm not sure this is a direction we want to go in.

With Markdown plugins, they will always introduce non-standard syntax, and I don't want to get into the habit of providing alternative syntaxes for every user's personal preferences. I think my comment in the linked issue still stands: https://github.com/facelessuser/pymdown-extensions/issues/2491#issuecomment-2399792024.

[robinlioret]

I do agree with you on the will to avoid alternative syntax. It can become messy very quick. I'm actually surprised that so few people encounter this issue.

I think non-standard syntax should be avoided if possible. Extensions should integrate as seamlessly as possible with the language to ensure best user experience. Not sure having the users customizing their Markdown formatter is something we want though. That is something to consider.

However, I won't insist, you've made your point in the issue's comment.

Please consider formatting standard for the new features. I really like my auto-format on save, very good for consistency across teams.

Should we close this PR without merging ?

[facelessuser]

Extending Markdown is hard. New syntax can break syntax highlighting, formatters, a number of things. The benefits is it allows you to do more. Those are the tradeoffs.

The reason I created the Block syntax was to provide a way where I don't have to keep creating new syntax for new functionality.

In Python Markdown, the header must be a self-contained block that is consumed all at once, it can't be consumed in parts. This is due to the complexity of the parser.

Originally, I had proposed that the header could be extended like so:

/// admonition | Some Title
/ Yaml: key
/   Nested: yaml
/ etc:
Content
///

I'd probably be okay bringing this back if people really desired it (optionally). I'm not a big fan of @ mainly because it conflicts with @username and such. I don't want to reuse this syntax for something else.

[robinlioret]

Thanks for the precision. I think I understand the goal. We need a marker for Yaml ish headers that could later be used for other extensions. So it should not interfer with other syntax, but be easy to write and lite to read and parse.

In these conditions @ is not a good solution, I agree.

What about ..., ::: or +> instead ?

[facelessuser]

I'm not looking to use up more unique symbols or symbol combinations that may conflict with some other extension. I'm open to optionally extending the header, similar to what I showed. It's something I had done previously, and we could optionally reinstate it again.