Comentarios en Markdown

¿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 .

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).

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 .

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).

• No hay líneas vacías, con<> 13+, 15-
• Línea vacía antes del comentario, usando<> 20+, 8-
• Líneas vacías alrededor del comentario, usando<> 20+, 8-
• ¿Sin líneas vacías, usando# 13+ 1? 14-
• ¿Línea vacía antes del comentario, usando # 23+ 1? 4-
• ¿Líneas vacías alrededor del comentario, usando# 23+ 1? 4-
• Comentario HTML con 3 guiones 1+ 2? 25- de la respuesta de chl (tenga en cuenta que esta es una sintaxis diferente)

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)

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.

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

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.

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.
-->

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.

¿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í.

Divulgación: escribí el complemento.

Como la pregunta no especifica una implementación específica de rebajas, me gustaría mencionar el complemento de comentarios para python-markdown , que implementa el mismo estilo de comentario de pandoc mencionado anteriormente.

<!--- ... --> 

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.

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

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.

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.

Puedes probar

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

Puedes hacer esto (bloque YAML):

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

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