Disable markdown indented code blocks by default

[zachleat]

In markdown there is a specific feature called Indented Code Blocks that causes much confusion! We have a big warning on the docs about it.

https://www.11ty.dev/docs/languages/markdown/#there-are-extra-and-in-my-output

Awhile back @drewm posted a lovely workaround to opt-out of this feature.

eleventyConfig.setLibrary("md", markdownIt(options).disable('code'));

https://twitter.com/drewm/status/1167821259662663682

I’d like to change the default Eleventy behavior to do this as well. Maybe even in 2.0 👀

Related: #402 #180 #1971 (#1635 maybe) and part of https://twitter.com/brob/status/1530620544680337412 from @brob and probably a bunch of others

[zachleat]

This would, of course, allow folks to re-enable the feature by using markdown-it’s enable instead of disable:

// Not this
// eleventyConfig.setLibrary("md", markdownIt(options).enable('code'));

// Opt-in via new 2.0 amendLibrary Configuration API method.
eleventyConfig.amendLibrary("md", mdLib => mdLib.enable('code'));

[jina]

YESSSSSS. This is such a pain point.

[pdehaan]

But I think the problem is that now I need to figure out what markdownIt() is, and which default settings Eleventy uses vs markdown-it defaults (which we outline on https://www.11ty.dev/docs/languages/markdown/#optional-set-your-own-library-instance, if you know where to look for it; spoiler: html: true (markdown-it default is false)).

Does it make more sense to add it as some new config flag?

eleventyConfig.markdownCodeIndent(false);

Liquid has an .setLiquidOptions() API, but I don't think that'd help us here (although it might make it easier to set default markdown-it options without needing to create a custom library instance just to set one option). And something like .setMarkdownOptions({code: false}); to disable code blocks (or ideally code blocks disabled by default and reenabled via {code: true}) might be too obscure and crossing streams.

[brob]

I prefer using my own code block syntax (liquid or nunjucks tag) and have been bitten by this a number of times.

Totally in agreement on this.

Additionally, I feel like any time something behaves unexpectedly is also a time for new users (and often newer devs) to get very confused. When magic happens, it should be more explicit.

I'd be curious to know how many folks actively use tab-based code blocks. To me, that's a relatively unintuitive way of handling it on markdown's part (but that ship has sailed)

[solution-loisir]

I think this would be a very sensible default since I feel that most users don't even know about the feature and it creates a gotcha. Personally, I've been desabling the code feature in every projects.

[AleksandrHovhannisyan]

Just to clarify, this doesn't break code blocks or inline code, right? I tried it out and it seems to work fine, and I'm also 100% in support of this since it's bitten me way too many times. I do agree that it's probably better to stick it behind an option, though, and maybe set it to true by default while allowing users to opt out if they need to.

[zachleat]

@AleksandrHovhannisyan correct, the traditional method (triple backtick) for code blocks and inline code (single backtick) in Markdown both still work when .disable("code") is in play.

Enabling or disabling the triple backtick feature is referenced as fence in markdown-it and the single backtick feature is backticks

https://github.com/markdown-it/markdown-it#manage-rules

[zachleat]

Per your comment @pdehaan I think this might be a good option if the feature had some modicum of popularity 😅. From the feedback here so far, it seems universally hated 😳 (and to be fair, same from me) #2438 (comment)

[MattWilcox]

Agreed, the "indent for code" was a mistake in the design of Markdown IMO. Get rid! :)

[tabatkins]

Yes please. Omitting indented code blocks is the major divergence that Bikeshed-flavored Markdown makes from CommonMark as well; it's a terrible misfeature on it's own and is even worse when combined with markup.