Comentarios en Markdown

¿Cuál es la syntax para almacenar un comentario en un archivo de rebajas, 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 las que requieren implementaciones específicas) hacen que los comentarios se incluyan en el HTML de salida, incluso si no se muestran.

Si desea un comentario que sea estrictamente suyo (los lectores del documento convertido no deberían poder verlo, incluso con “ver fuente”), podría (ab) usar las tags de enlace (para usar con enlaces de estilo de referencia) que son disponible en la especificación de Markdown básica:

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 para guardar una pulsación de tecla), también es posible usar # (que es un objective de hipervínculo legítimo) en lugar de <> :

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

Para una portabilidad máxima, es importante insertar una línea en blanco antes y después de este tipo de comentarios, ya que algunos analizadores de Markdown no vinculan las definiciones con 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 emitirá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 de Markdown, ya que es parte de la especificación principal. (incluso si el comportamiento cuando se definen múltiples enlaces, o cuando se define un vínculo pero nunca se utiliza, no se especifica estrictamente).

Yo uso tags HTML estándar, como

  

Tenga en cuenta el triple tablero. La ventaja es que funciona con pandoc al generar resultados TeX o HTML. Más información está disponible en el grupo pandoc-discuss .

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

La syntax 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 especificación de Markdown estricta CommonMark solo funciona según lo previsto con esta syntax (y no con <> y / o una línea vacía)

Para probar esto, utilizaremos 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 procesado).

  • Sin 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-
  • ¿Vaciar la línea antes del comentario, usando # 23+ 1? 4-
  • ¿Vaciar las líneas alrededor del comentario, usando # 23+ 1? 4-
  • Comentario HTML con 3 guiones 1+ 2? 25- de la respuesta del chl (tenga en cuenta que esta es una syntax diferente)

Esto prueba las declaraciones anteriores.

Estas implementaciones fallan las 7 pruebas. No hay posibilidad de utilizar 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 OctopStyle también funcionará.

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

Las tags 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 poner comentarios dentro de tags 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 NOT support comments

aparece de la siguiente manera en un NAVEGADOR

We do support comments

Esto funciona en GitHub:

 [](Comment text goes here) 

El HTML resultante se ve así:

  

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

Consulte también Critic Markup, respaldado por un número cada vez mayor de herramientas de reducción.

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é tal si ponemos los comentarios en un bloque R no evaluativo y sin eco? es decir,

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

Parece que funciona bien para mí.

Divulgación: escribí el complemento.

Dado que la pregunta no especifica una implementación de rebajas específica, me gustaría mencionar el plugin 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 aparecían en html. Lo siguiente funcionó:

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

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

Los usuarios de Vim Instant-Markdown deben usar

  

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 proporciona un resaltado de syntax más adecuado de los comentarios en comparación con muchas de las otras soluciones propuestas, al menos en mi entorno ( vim , vim-pandoc y vim-pandoc-syntax ).

Uso los comentarios de bloque yaml en combinación con los comentarios html-inline, ya que los html-comments no pueden anidarse . Lamentablemente, no hay forma de comentar en bloque dentro del metabloque yaml , por lo que cada línea debe comentarse individualmente. Afortunadamente, solo debería haber una línea en un párrafo suavizado.

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

 nmap b }oO...{ji#O---2 nmap v {jddx}kdd 

Utilizo , como mi -clave, entonces ,b y ,v comente y descomente un párrafo, respectivamente. Si necesito comentar varios párrafos, asigno j,b a una macro (generalmente Q ) y ejecuto (por ej., ( 3Q ). Lo mismo funciona para descomentar.

kramdown -el motor de rebajas basado en Ruby que es el predeterminado para Jekyll y, por lo tanto, GitHub Pages- tiene soporte de comentarios incorporado a través de su syntax 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 para otros motores Markdown.

Puedes probar

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