Les commentaires dans Markdown

j'utilise des balises HTML standard, comme

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

Notez le triple tiret. L'avantage est qu'il fonctionne avec pandoc lors de la génération de sortie TEX ou HTML. De plus amples informations sont disponibles sur le groupe pandoc-discussion .

cette petite recherche prouve et raffine la réponse de Magnus

la syntaxe la plus indépendante de la plateforme est

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

les deux conditions sont importantes:

1. utilisant # (et non <> )
2. Avec une ligne vide avant le commentaire . Ligne vide après le commentaire n'a pas de impact sur le résultat.

La stricte Markdown spécification CommonMark ne fonctionne qu'avec cette syntaxe (et non <> et/ou une ligne vide)

pour le prouver, nous utiliserons le Babelmark2, écrit par John MacFarlane. Cet outil vérifie le rendu d'un code source particulier dans 28 implémentations de Markdown.

( + - a réussi l'essai, - - n'a pas passé, ? - laisse quelques ordures qui n'est pas montré dans rendu HTML).

• Pas de lignes vides, à l'aide de <> 13+, 15-
• ligne vide avant le commentaire, en utilisant <> 20+, 8-
• lignes vides autour du commentaire, en utilisant <> 20+, 8-
• Pas de lignes vides, à l'aide de # 13+ 1? 14-
• ligne vide avant le commentaire, en utilisant # 23+ 1? 4-
• lignes vides autour du commentaire, en utilisant # 23+ 1? 4-
• commentaire HTML avec 3 traits d'union 1+ 2? 25-de la réponse de chl (notez que c'est une syntaxe différente)

cela prouve les déclarations ci-dessus.

ces implémentations échouent tous les 7 tests. Il n'y a aucune chance d'utiliser des commentaires exclus-sur-rendu avec eux.

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

si vous utilisez Jekyll ou octopress la suite fonctionnera aussi.

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

les étiquettes liquides {% comment %} sont analysées en premier et enlevées avant même que le processeur MarkDown ne s'y retrouve. Les visiteurs ne verront pas quand ils essaient de voir la source à partir de leur navigateur.

une alternative est de mettre des commentaires dans des balises HTML stylisées. De cette façon, vous pouvez modifier leur visibilité au besoin. Par exemple, définissez une classe de commentaire dans votre feuille de style CSS.

.comment { display: none; }

puis, le MARKDOWN amélioré suivant

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

apparaît comme suit dans un navigateur

We do support comments

cela fonctionne sur GitHub:

[](Comment text goes here)

le HTML résultant ressemble à:

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

Qui est essentiellement un lien vide. Évidemment, vous pouvez le lire dans la source du texte rendu, mais vous pouvez le faire sur GitHub de toute façon.

Voir Aussi Markup de critique, supporté par un nombre croissant d'outils 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.

Que Diriez-vous de mettre les commentaires dans un bloc non-eval, non-echo r? c'est à dire,

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

Semble bien fonctionner pour moi.

Divulgation: j'ai écrit le plugin.

comme la question ne spécifie pas d'implémentation markdown spécifique , j'aimerais mentionner le Plugin Comments pour python-markdown , qui implémente le même style de commentaire pandoc mentionné ci-dessus.

<!--- ... --> 

ne fonctionne pas dans Pandoc Markdown (Pandoc 1.12.2.1). Les commentaires apparaissent toujours en html. Ce qui suit a fonctionné:

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

utilisez ensuite l'extension + footnote. Il s'agit essentiellement d'une note de bas de page, qui n'est jamais mentionné.

Vim Instant-Markdown les utilisateurs ont besoin d'utiliser

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

pour pandoc, une bonne façon de bloquer les commentaires est d'utiliser un metablock yaml, comme suggéré par l'auteur pandoc . J'ai remarqué que cela donne une syntaxe plus appropriée mettant en évidence les commentaires par rapport à beaucoup d'autres solutions proposées, au moins dans mon environnement ( vim , vim-pandoc , et vim-pandoc-syntax ).

j'utilise les commentaires de bloc de yaml en combinaison avec les commentaires html-inline, depuis html-les commentaires ne peuvent pas être emboîté . Malheureusement , il n'y a aucun moyen de bloc commentant dans le metablock yaml , donc chaque ligne doit être commentée individuellement. Heureusement, il ne devrait y avoir qu'une seule ligne dans un paragraphe contenant un logiciel.

dans mon ~/.vimrc , j'ai mis en place des raccourcis personnalisés pour les commentaires de bloc:

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

j'utilise , comme mon <Leader> -clé, de sorte que ,b et ,v et supprimez les marques de commentaire un paragraphe, respectivement. Si je dois commenter plusieurs paragraphes, je mets j,b sur une macro (habituellement Q ) et j'exécute <number-of-paragraphs><name-of-macro> (par exemple 3Q ). Les mêmes travaux pour décommenter.

kramdown - le moteur markdown basé sur Ruby qui est la valeur par défaut pour Jekyll et donc GitHub Pages - a intégré le support de commentaire à travers sa syntaxe d'extension :

{::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{:/}

ceci a l'avantage de permettre des commentaires en ligne, mais l'inconvénient de ne pas être portable à d'autres moteurs de Markdown.

vous pouvez essayer

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