Comentarios en Markdown


1402

¿Cuál es la sintaxis para almacenar un comentario en un archivo de descuento, por ejemplo, un comentario CVS $ Id $ en la parte superior del archivo? No encontré nada en el proyecto de rebajas .


10
Leyendo entre líneas, parece que desea adjuntar metadatos a su Markdown. Por esa razón, sugeriría usar un preprocesador que le permita agregar un encabezado. Para un ejemplo, vea el asunto frontal de Jekyll . Para otro ejemplo, vea cómo Basho usa a Middleman para su documentación . (Nota: Esta no es una respuesta directa a la pregunta, por eso la comparto como comentario).
David J.

2
Vea también cómo MultiMarkdown admite metadatos .
David J.

Aquí hay un punto de referencia de diferentes tipos de comentarios con diferentes analizadores en Babelmark .
Ulysse BN

Respuestas:


1456

Creo que todas las soluciones propuestas anteriormente (aparte de aquellas que requieren implementaciones específicas) dan como resultado que los comentarios se incluyan en el HTML de salida, incluso si no se muestran.

Si desea un comentario estrictamente para usted (los lectores del documento convertido no deberían poder verlo, incluso con "ver fuente") podría (ab) usar las etiquetas de enlace (para usar con enlaces de estilo de referencia) que son disponible en la especificación central de Markdown:

http://daringfireball.net/projects/markdown/syntax#link

Es decir:

[comment]: <> (This is a comment, it will not be included)
[comment]: <> (in  the output file unless you use it in)
[comment]: <> (a reference style link.)

O podrías ir más allá:

[//]: <> (This is also a comment.)

Para mejorar la compatibilidad de la plataforma (y guardar una pulsación de tecla) también es posible usar #(que es un objetivo de hipervínculo legítimo) en lugar de <>:

[//]: # (This may be the most platform independent comment)

Para obtener la máxima portabilidad, es importante insertar una línea en blanco antes y después de este tipo de comentarios, porque algunos analizadores de Markdown no funcionan correctamente cuando las definiciones rozan el texto normal. La investigación más reciente con Babelmark muestra que las líneas en blanco antes y después son importantes. Algunos analizadores generarán el comentario si no hay una línea en blanco antes, y algunos analizadores excluirán la siguiente línea si no hay una línea en blanco después.

En general, este enfoque debería funcionar con la mayoría de los analizadores Markdown, ya que es parte de la especificación central. (incluso si el comportamiento cuando se definen múltiples enlaces, o cuando se define un enlace pero nunca se usa, no se especifica estrictamente).


145
[//]: # "Comment"y [//]: # (Comment)parece funcionar en una variedad más amplia de implementaciones, porque #es un URI relativo válido. GitHub, por ejemplo, rechaza <>, y toda la línea se hace visible. También vale la pena señalar que las etiquetas de enlace a menudo necesitan estar separadas de otro contenido por una línea en blanco.
Zenexer

66
Para ser más independiente de la plataforma, también necesita una línea vacía antes del comentario. Vea las pruebas: stackoverflow.com/a/32190021/2790048
Nick Volynkin el

66
¿Se puede usar para comentarios de varias líneas?
crypdick

44
@RovingRichard Sí, al menos en Pandoc esto funciona para comentarios multilínea si no hay líneas en blanco en el bloque comentado (los saltos de línea individuales están bien). Utilizo el enfoque de Magnus para comentarios en bloque y el enfoque HTML de chl para comentarios en línea (aunque generalmente solo 2 guiones). De esta manera, puedo bloquear los comentarios que ya contienen comentarios HTML en línea.
joelostblom

44
Solo para su información, pero si está creando una tabla de contenido con Pandoc, esto generará una advertencia sobre referencias de enlaces duplicados. (Estas son solo advertencias, el TOC aún se creará.)
Karl Giesing

995

Yo uso etiquetas HTML estándar, como

<!---
your comment goes here
and here
-->

Tenga en cuenta el triple guión. La ventaja es que funciona con pandoc cuando se genera salida TeX o HTML. Hay más información disponible en el grupo de discusión de pandoc .


73
Si entiendo correctamente, el guión triple hace que Pandoc ignore el comentario cuando analiza el archivo de rebajas. Pero si usa otro motor de rebajas, el comentario se mostrará en el HTML generado (y, por lo tanto, será visible con "ver fuente"). Así que debes tener cuidado con lo que pones en ese comentario;)
cberzan

55
¿Puedes explicar cómo Pandoc trata los guiones triples de manera diferente al doble? Cuando experimenté con ellos, parecían tratarse de la misma manera. Además, la guía del usuario de Pandoc solo dice "El HTML sin formato se pasa sin cambios en HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown y Textile, y se suprime en otros formatos". Los guiones triples no parecen tener más privilegios que los dobles.
dkim

1
@dkim Los comentarios con triple guión se ignoran y se descartan de la salida HTML. Este no es el caso con los comentarios de doble trazo que se insertan en el archivo HTML. Este sigue siendo el caso con la última versión de Pandoc (1.10).
chl

32
Si el guión triple es significativo, estos no son comentarios "HTML estándar".
tripleee el

17
Nota para los Googlers: desafortunadamente, esto no funciona en GitHub Markdown, y terminé usando la solución de Magnus.
Daniel Buckmaster

198

Esta pequeña investigación prueba y refina la respuesta de Magnus.

La sintaxis más independiente de la plataforma es

(empty line)
[comment]: # (This actually is the most platform independent comment)

Ambas condiciones son importantes:

  1. Usando #(y no <>)
  2. Con una línea vacía antes del comentario . La línea vacía después del comentario no tiene impacto en el resultado.

La estricta especificación Markdown CommonMark solo funciona según lo previsto con esta sintaxis (y no con <>y / o una línea vacía)

Para probar esto, usaremos el Babelmark2, escrito por John MacFarlane. Esta herramienta verifica la representación de un código fuente particular en 28 implementaciones de Markdown.

( +- pasó la prueba, -- no pasó, ?- deja algo de basura que no se muestra en HTML renderizado).

Esto prueba las declaraciones anteriores.

Estas implementaciones fallan en las 7 pruebas. No hay posibilidad de usar comentarios excluidos en el render con ellos.

  • cebe / markdown 1.1.0
  • cebe / markdown MarkdownExtra 1.1.0
  • cebe / markdown GFM 1.1.0
  • s9e \ TextFormatter (Fatdown / PHP)

3
Excelente herramienta de prueba exhaustiva! Parece que tienes razón que # funciona para todos menos para GFM y <> funciona para GFM pero no para un par más. Lástima que GFM sea un caso de esquina y también un sabor muy popular.
placas

1
Parece que s9e \ TextFormatter funciona # desde el 21 de enero de 2016. Cebe todavía no lo maneja.
Troy Daniels

1
Curiosamente, si el comentario contiene (...)solo, lo rompe. Al menos en Visual Studio Code 1.19.
Royi

1
y, por lo tanto, para los usuarios de vim que desean comentar todo un archivo a la vez:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.

¿Qué dice sobre Markdown que Bablemark2 existe?
TC Proctor

55

Si está utilizando Jekyll o Octopress, el siguiente también funcionará.

{% comment %} 
    These commments will not include inside the source.
{% endcomment %}

Las etiquetas Liquid {% comment %}se analizan primero y se eliminan antes de que el procesador MarkDown llegue a ellas. Los visitantes no verán cuando intenten ver la fuente desde su navegador.


2
Jinja2 = {#comentarios multilínea aquí#}
John Mee

29

Una alternativa es colocar comentarios dentro de etiquetas HTML estilizadas. De esta manera, puede alternar su visibilidad según sea necesario. Por ejemplo, defina una clase de comentario en su hoja de estilo CSS.

.comment { display: none; }

Luego, el siguiente MARKDOWN mejorado

We do <span class="comment">NOT</span> support comments

aparece como sigue en un NAVEGADOR

We do support comments


55
Copiar / pegar probablemente terminará copiando el texto "comentado" y el texto normal, así que tenga cuidado al usar esto. Fácilmente podría producir resultados inesperados para alguien que copia un bloque de texto.
Eilon

44
@Eilon también la accesibilidad para esto sería terrible
Ethan

La accesibilidad de los motores compatibles omitirá correctamente la visualización: sin texto.
aredridel

28

Esto funciona en GitHub:

[](Comment text goes here)

El HTML resultante se ve así:

<a href="Comment%20text%20goes%20here"></a>

Que es básicamente un enlace vacío. Obviamente, puede leer eso en la fuente del texto renderizado, pero puede hacerlo en GitHub de todos modos.


66
Definitivamente lo es, pero en realidad es la única respuesta hasta ahora que siempre funciona en GitHub, por ejemplo, en listas.
jomo

Llegué a la misma solución. Es el único en el que puedo trabajar para comentarios en línea, por ejemplo some text [](hidden text) blah blah.
c24w

3
Esto ya no funciona en github a partir del 2019-03-08, se presenta como está[](Comment text goes here)
dogmatic69

19

Los usuarios de Vim Instant-Markdown deben usar

<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->

18

También vea Critic Markup, respaldado por un número creciente de herramientas de Markdown.

http://criticmarkup.com/

Comment {>> <<}

Lorem ipsum dolor sit amet.{>>This is a comment<<}

Highlight+Comment {== ==}{>> <<}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.==}{>>confusing<<} Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

55
Creo que uno de los problemas con tales "pseudo" estándares es que no son portátiles. En algunos sitios web, estos funcionarán perfectamente, en otros, no.
Willem Van Onsem

14

¿Qué hay de poner los comentarios en un bloque R sin evaluación ni eco? es decir,

```{r echo=FALSE, eval=FALSE}
All the comments!
```

Parece que funciona bien para mí.


2
Además, siéntase libre de hacer cosas como cat("# Some Header")dentro de los bloques de código "comentados" y usarlos results = "asis", y puede agregar secciones comentadas completas a su código que pueden activarse / desactivarse al alternar eval = FALSE, ya que la evaluación R se realiza antes de compilación de pandoc. Gracias por la idea!
MichaelChirico


11
<!--- ... --> 

No funciona en Pandoc Markdown (Pandoc 1.12.2.1). Los comentarios aún aparecieron en html. Lo siguiente funcionó:

Blank line
[^Comment]:  Text that will not appear in html source
Blank line

Luego use la extensión de pie de página +. Es esencialmente una nota al pie de página a la que nunca se hace referencia.


Esto me gusta más, porque no genera ningún resultado en absoluto. Para Bitbucket este prefijo es suficiente: [#]: .
ceving

7

Lo siguiente funciona muy bien

<empty line>
[whatever comment text]::

ese método aprovecha la sintaxis para crear enlaces a través de la referencia,
ya que la referencia de enlace creada con [1]: http://example.orgno se representará, del mismo modo, tampoco se representará ninguno de los siguientes

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever

Esta (primera variante probada) funciona pandoctan bien como las instancias en línea actuales de Gitlab y GitHub .
doak

5

Para pandoc, una buena forma de bloquear comentarios es usar un metabloque yaml, como lo sugiere el autor de pandoc . Me he dado cuenta de que esto da resaltado de sintaxis más adecuada de los comentarios en comparación con muchas de las otras soluciones propuestas, al menos en mi entorno ( vim, vim-pandocy vim-pandoc-syntax).

Utilizo comentarios de bloque yaml en combinación con comentarios en línea html , ya que los comentarios html no se pueden anidar . Desafortunadamente, no hay forma de bloquear los comentarios dentro del metabloque yaml , por lo que cada línea debe comentarse individualmente. Afortunadamente, solo debe haber una línea en un párrafo de formato suave.

En mi ~/.vimrc, he configurado accesos directos personalizados para comentarios de bloque:

nmap <Leader>b }o<Esc>O...<Esc>{ji#<Esc>O---<Esc>2<down>
nmap <Leader>v {jddx}kdd

Utilizo ,como mi <Leader>tecla, de modo ,by ,vcomentario y elimine el comentario de un párrafo, respectivamente. Si necesito comentar varios párrafos, me mapeo j,ba una macro (generalmente Q) y ejecuto <number-of-paragraphs><name-of-macro>(p 3Q. Ej. ( ). Lo mismo funciona para descomentar.


5

kramdown , el motor de reducción basado en Ruby que es el predeterminado para Jekyll y, por lo tanto, para las páginas de GitHub, tiene soporte para comentarios incorporado a través de su sintaxis de extensión :

{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

Do you see {::comment}this text{:/comment}?
{::comment}some other comment{:/}

Esto tiene el beneficio de permitir comentarios en línea, pero la desventaja de no ser portátil a otros motores Markdown.


4

Puedes probar

[](
Your comments go here however you cannot leave
// a blank line so fill blank lines with
//
Something
)

4

Puedes hacer esto (bloque YAML):

~~~
# This is a
# multiline
# comment
...

Lo intenté solo con salida de látex, confirma para otros.


Funciona con salida HTML también.
petzi 05 de

No estoy seguro de si la confirmación de Daniel de la salida html es correcta. Lo hice con un archivo de salida html y ejecuté "pandoc --bibliography paper.bib -o paper.html paper.md" y el HTML mostró las líneas de comentarios.
markgalassi
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.