Error "Unexpected character !" from remark when parsing HTML comment

[emertechie]

I'm trying to use Vale in a Docusaurus project. It works well, but if I need to add a special Vale comment like <!-- vale off --> to a .md file to ignore Vale errors for a certain block of code, this causes parsing issues with remark.

I have a build step that checks my markdown files by running npx remark . --frail --quiet, but this fails to process files with those HTML comments with the following error:

Unexpected character `!` (U+0021) before name

Any idea how to resolve this?

[Josh-Cena]

You need to either switch to the CommonMark processor (https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark), or use the MDX comment: {/* vale off */}.

[slorber]

MDX v2/v3 doesn't support html comments anymore (but MDX v1 did):

https://mdxjs.com/playground/

---

Normally Docusaurus v3 has a compat layer to still allow HTML comments in MDX docs, even without CommonMark mode. In this case, we add this remark plugin automatically: https://github.com/leebyron/remark-comment

I tried the <!-- vale off --> comment and it definitely works, so @emertechie if it's your Docusaurus site failing, please provide a repro where we can see the error in action.

Remember that you can disable this compat layer so make sure you didn't do that: https://docusaurus.io/blog/releases/3.0#markdown

export default {
  markdown: {
    mdx1Compat: {
      comments: false, // You need to keep it true
    },
  },
};

---

If it's only your build step that is failing, then your build step should register the remark-comment plugin on its own to ensure HTML comments are allowed. This build step is not under our control, so it's your responsibility to ensure it works.

[emertechie]

Thanks for the detailed reply @slorber. Yes it was just my bad with the build step - I hadn't plugged remark-comment in there. So for the benefit of anyone else, you need to install that plugin and then do:

npx remark . --frail --quiet --use remark-comment