Giters

DavidAnson / markdownlint

A Node.js style checker and lint tool for Markdown/CommonMark files.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

HTML disable/enables comments triggered when inside Markdown inline code

rachmari opened this issue · comments

commented

I noticed recently that even when an HTML enable/disable comment is inside inline code (e.g., <!-- markdownlint-enable -->), it is still executed.

I noticed that the regex /<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi does not account for whether the disable/enable comments are inside inline code. If a negative lookbehind is used /((?<!)<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi the HTML comments are properly ignored.

Are Markdown inline code tags ignored by design?

For some background about why we ran into this issue, we write documentation for how to use our custom Markdownlint linter for external contributors (https://github.com/github/docs/blob/main/content/contributing/collaborating-on-github-docs/using-the-content-linter.md). That documentation uses some HTML pre tags and other things to get the Markdown to render properly, which causes other issues in our rendering pipeline.

In our docs, we'd like to write something like this in a Markdown file while also still being able to run Markdownlint on the same file:

You can use the  HTML comment `<!-- markdownlint-disable -->` to disable all rules

This will effectively disable all rules, and prevent any errors from being raised. On the opposite side, using <!-- markdownlint-enable --> will enable all rules, even rules we don't include in our custom config.

commented

I think your lookbehind got garbled, but I'd be reluctant to "fix" this too narrowly as there is no guarantee the backticks are tight to the comment (or that nothing else is in between).

What do you think about this approach that works today: https://dlaa.me/markdownlint/#%25m%23%20Issue%201213%0A%0AText%20%60%3C!--%20markdownlint-disable%20--%3E%60%20text%0A%0A%3C!--%20markdownlint-restore%20--%3E%0A%0A%23%20Extra%20H1%0A

commented

@DavidAnson sorry for the typo in the issue summary. There was an extra ` (Fixed).

What do you think about this approach that works today:

I didn't know about the restore config option. Does this option restore back to the rule configuration prior to any disables/enables? I see the description in the README, but it's not clear whether it restores back to the captured configuration. It seems to imply that the restore option must be used only after the capture option is used. Is that accurate?

commented

If you scroll down a bit in the README, it says there is an implicit capture at the top of every document. It's not wrong to pair every restore with a capture, but it's unnecessary if nothing has been disabled or enabled up to that point.

commented

@DavidAnson thank you for the explanation. In that case, the solution you provided does work for us. Thank you! ✨