Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Proposal: Standardize a native syntax for Markdown comments

Abierto
  • ¿Algo no está bien?
#844 5 comentarios 1 reacción 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
markdown
Área
documentation

Línea de trabajo

Start by reading the CommonMark specification and comparing the comment conventions named in the issue: HTML comments, link-reference hacks, Obsidian’s %% syntax, and language-style delimiters. The issue proposes standardizing a syntax but leaves the choice open, so done would require settling on a syntax and specifying how it is omitted from the AST or HTML output.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

The core spirit and mission of CommonMark is to standardize Markdown to ensure interoperability across different platforms. However, the lack of a standardized syntax for comments (text that is ignored by renderers and not outputted to HTML) remains a major omission.

Because the spec has left this out, a highly fragmented ecosystem has emerged. There is a deep disconnect between markdown editors and markdown viewers:

  • The HTML Comment Hack (): Many users rely on this, but it is technically passed through to the HTML output. This leaks internal notes to the production source code, which is highly undesirable for security, privacy, and file size reasons.

  • The Link Reference Hack ([^comment]: or [//]: #): Various editors and parsers have adopted different link-label hacks to trick compilers into ignoring text.

  • Custom Syntaxes (%%comment%%): Apps like Obsidian use their own internal formatting, which completely breaks portability when the file is read by standard CommonMark parsers like GitHub or Jekyll.

This creates "disconnected camps" where a document containing comments looks perfect in a specific editor but leaks or breaks entirely when published to a standard viewer.

I would like to propose a native, standardized syntax for comments within the CommonMark specification.

A syntax that explicitly instructs the compiler to omit the wrapped text from the final abstract syntax tree (AST) or HTML output entirely.

Possible syntax directions already popular in the community include:

- %% Comment here %% (Used by Obsidian)
- [//]: # (Comment here) (A strictly regulated version of the link hack)
- // and /*   */ already popular with a few languages
- A dedicated syntax like [# Comment here #] or similar blocks.

Continuing to rely on the <!-- HTML comment --> approach, which fails the requirement of keeping draft notes hidden from the final production source code, or accepting that Markdown files will continue to lose portability between different vendor apps.

Standardizing comments aligns perfectly with CommonMark’s goal. It resolves a massive point of friction for technical writers, content creators, and developers who need to leave notes, TODOs, or metadata in their files without leaking them to the end-user.

Lenguaje dominante
Python
Estrellas
5.2k
Forks
360
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de commonmark/commonmark-spec

Todos los issues de commonmark/commonmark-spec

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.