allowIndentation docs are outdated about markdoc HOT 3 OPEN

Yes, indent-based code blocks are now disabled by default. The allowIndentation option is still relevant, however, because it tells the tokenizer to allow other block types to be parsed when indented.

For example, consider the following Markdoc source:

This is a test

    - This is another test

When the allowIndentation option is not enabled, the list is not recognized as such because it is indented more than three spaces, resulting in this output: <article><p>This is a test</p><p>- This is another test</p></article>. With the option enabled, the list tag parses as expected.

The reason we still don't turn this on by default is because content written with this sort of indentation will not parse as expected in a CommonMark-compliant parser. Users who want their Markdoc content to still be portable to other parsers should probably keep it turned off.

I can update the docs to clarify this and address that indent code blocks are now off by default regardless of the setting. Thanks for raising this. 👍

from markdoc.

Indented code blocks are a significant use case, though, especially with regards to portable content. Indented blocks are the only one supported by more "old-school" parsers including the original Gruber one, especially when dealing with content nested inside lists. For example, in Python-Markdown, even with the "extra" settings for code fences, you can't use code fences in lists, but you can use indented code blocks. Content that's written for these parsers can also be handled by CommonMark parsers, but disabling indented code breaks that.

I say this as someone who has been writing such content for 9 years, and finds a lot of the content incompatible with Markdoc because of the use of indented code blocks inside lists.

from markdoc.

@mDuo13 if you really need to parse content written with indented code blocks in Markdoc, you can still subclass Markdoc's Tokenizer class and set up an instance of MarkdownIt with whatever features (and specific plugins) you want.

from markdoc.