markdown-it-attrs not parsing properly in user guide

[wxwxwxwx9]

As shown in the image above, markdown-it-attr is not parsing the {.alert-info} properly and it appears as text in the output. It should have been applied as a class on the topmost list.

The specific example we are looking at is actually adapted from the documentation of markdown-it-attrs library.

I took a look into the issue to find out where the bug occured and it seemed to have came from the V3 baseline implementation.

The last working version that I identified was at the commit "Extend navbar highlighting to standard links and dropdowns".

I faced some difficulty in narrowing down the scope further as the commits seem to have some interdependence (e.g. commit A requires commit B, reverting to commit A and running markbind will result in errors when serving).

It will take some time and a bit of effort to isolate the bug and fix it. We probably want to sieve through the commits and look at where the markdown parser was modified. It could also have been due to the content processing flow changes.

I'll put this issue here first and revisit this when I'm done with other PRs. But feel free to take up this issue if you feel like it :-)

[ang-zeyu]

This is spec compliant to some level actually.

It worked before because we did nunjucks -> html (just to process <include/>) -> markdown -> html (misc).
So the things inside <include /> are exceptionally (wouldn't work with any other tag) rendered into the included file before being touched by markdown.

Now it's nunjucks -> markdown -> html recursively which means all tags get the same treatment. It would need an empty line before the <variable name="code"> tag in the docs for markdown to avoid rendering it, much like things inside <script/style/pre> tags (patch / support for that here).

I missed out quite a few lapses in the docs in that PR though. I fixed a few in #1479 but seems like missed a few more (also one more under the katex section) =\

[ang-zeyu]

An simple alternative (possibly) to this is to also treat <include> tags as "special" tags (<script/pre/style> according to commonmark) just for the markdown side, while treating it normally for the html side so the variable tags don't get parsed as text.

It's also "spec compliant", and would remove the need to pad <variable> tags before with an empty line.