Commented content of markdown files is rendered on website

[cason]

Notice on the ABCI++ documentation.

The content from https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#synchronyparamsmessagedelay to https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#timeoutparamsbypasscommittimeout is not present (rendered) in the corresponding Github page: https://github.com/cometbft/cometbft/blob/v0.38.x/spec/abci/abci%2B%2B_app_requirements.md#abciparamsvoteextensionsenableheight

Indeed we can see the tags for comments (<!– and –>) being rendered.

This is problematic, specially for ABCI, as parameters not present on that release, or not present at all, even on main (e.g., https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#timeoutparamspropose) are visible for uses using this platform.

[cason]

The easiest way out is to get rid of comments on the original repository.

[cason]

Update: this does not happen to all comments. It appears to happen only when there is no empty line before <!--.

[cason]

List of files possibly affected:

% grep "<\!-" . -R -l --exclude-dir=".github" --exclude-dir="./docs/rfc" --exclude-dir="./docs/architecture" --include "*.md"
./spec/abci/abci++_client_server.md
./spec/abci/abci++_app_requirements.md
./spec/abci/abci++_methods.md
./spec/light-client/accountability/README.md
./spec/light-client/verification/verification_002_draft.md
./spec/light-client/verification/verification_001_published.md
./spec/light-client/detection/detection_003_reviewed.md
./spec/light-client/detection/detection_001_reviewed.md
./spec/light-client/attacks/isolate-attackers_002_reviewed.md
./spec/light-client/attacks/isolate-attackers_001_draft.md
./spec/light-client/supervisor/supervisor_001_draft.md
./docs/core/rpc.md

[andynog]

Thank you for reporting this, @cason. I appreciate your effort. My concern is that using <!-- --> tags to hide content might cause some technical issues. However, what worries me more is that the specifications of each version should match its implementation. Therefore, instead of hiding the content, we should create a version that excludes irrelevant content for that particular version.

[cason]

Fully agree.