facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.67k stars 8.52k forks source link

Markdown html comment parsing error if there is a trailing space #8670

Closed darwintree closed 1 year ago

darwintree commented 1 year ago

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

Html comment in markdown files raises a syntax error if there is a trailing space. For example, the markdown code: <!-- ![blabla.png](/img/blabla.png)--> raises an error but <!-- ![blabla.png](/img/blabla.png)--> doesn't.

Reproducible demo

https://github.com/Conflux-Chain/conflux-documentation/tree/l10n_translation-pipeline

Steps to reproduce

The error could be reproduced by using the demo in Github codespace. You can simply run yarn zh. Or:

  1. open a project with a existed markdown file
  2. add the following content to the tail of any markdown file
    <!-- ![blabla.png](/img/blabla.png)-->
    <!-- ![blabla.png](/img/blabla.png)--> 
    <!-- ![blabla.png](/img/blabla.png)-->

    Note: there is a trailing space for the second line

  3. run the project, then the error should be like: image Noting that the first and third line will be successfully parsed
  4. remove the trailing space of the second line
  5. the error disappears

Expected behavior

  1. The html comment with a trailing space is expected to be parsed successfully.
  2. If this is hard to accomplish, at least the right error should be raised but not an "unexpected token" error

Actual behavior

I am integrating my project with Crowdin to the i18n. The default strategy of Crowdin would convert the trailing \n to a space in certain circumstances. So this is the source doc and here is an auto-generated untranslated file by Crowdin.

The command yarn start --locale zh-Hans but the compilation fails. Although Crowdin slightly changes the structure of the original file, I think it is acceptable because other tools, like vs code, won't raise an error. As far as I am concerned, this might be a bug of docusaurus or its markdown parsing engine. (This is not the actual error, but is exactly same except for line number) image

Your environment

Self-service

slorber commented 1 year ago

Apparently, this is a bug in MDX 1, reproducible in the MDX 1 playground: https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/ MDX 1 is not updated anymore.

We'll upgrade soon to MDX 2 (Docusaurus v3, breaking change) but it does not use html comments by default so you'll have to use JSX comments instead.

Closing because we can't really act on it apart upgrading to MDX 2