HTML comments hidden in texts but displayed in DocCard

[tomasdahlqvist]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Mutli-line HTML comments are not removed from previews. The preview then contains the first line of the comment instead of the actual content.

Reproducible demo

https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic-typescript?file=docs%2Ftutorial-basics%2Fcreate-a-document.md

Steps to reproduce

1. Change the start of the tutorial page create-a-document to

---

sidebar_position: 2

Create a Document

Documents are ...
2. View the card layout from the page "Tutorial - Basics"
3. The description in the card is "<!-- black"

Expected behavior

The html comment should be ignored even if it is multi-line.

Actual behavior

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[5AIPAVAN]

I want to work on this @tomasdahlqvist , can you please assign this to me :-)

[TRIPLE-ADE]

Can you assign this to me

[slorber]

Note HTML comments are not valid MDX syntax, and Docusaurus v3 interprets .md docs as MDX by default (unless you use format: md)

We do add back support for HTML comments as a workaround to ease the adoption of Docusaurus v3, but it's preferable to use either format: md or to avoid using HTML comments in the first place. You'd better choose between CommonMark or MDX, not a mix of both. In the future we might remove support for HTML comments in MDX docs. The reason is that we don't want to "extend" the MDX syntax. Doing so will also mess up with external tooling that won't be able to understand why your MDX files have HTML comments, since it's invalid (Prettier, ESLint, VSCode, Biome etc...)

That being said, we add back support for HTML comments through a lib: https://github.com/leebyron/remark-comment

There was a bug in multiline comments that I tried to fix in this PR: leebyron/remark-comment#3
This official repo is not maintained anymore and the PR hasn't been merged so I published a fork that Docusaurus uses: https://www.npmjs.com/package/@slorber/remark-comment

I'm not an expert in extending Markdown syntax and it's probable that my attempt has unsupported edge cases.

[slorber]

Oh damn, I misunderstood the problem.

Indeed the card will display the comment, but not only. This is because the card description has to be a pure string and we do a best effort to extract and serialize that string to display it in that card.

Our docs tell you the behavior:

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs

The first line of Markdown content

This is not only used in the card, but also on SEO description metadata and eventually other places.

Unfortunately we won't really be able to solve this. The description has to be a pure string. We provide a default but if the default is not good enough to you, you should rather provide an explicit description front matter instead. It's always better to be explicit, the default is only there for getting started fast, not for the best outcome.

[tomasdahlqvist]

I found it strange that one line comments work but not multiline. Also in for example #9691 the and /* */ syntax are both viable.
Shouldn't the standard be that either no comments work or all comments work?

[slorber]

This is because the logic that creates the excerpt/description is not a real markdown parser but a best-effort regexp. Using a real parser for that would have significant overhead, and it's preferable to not penalize all users in terms of performance, and ask them to provide an explicit description.