Commentaires dans Markdown

Quelle est la syntaxe pour stocker un commentaire dans un fichier de démarque, par exemple un commentaire CVS $ Id $ en haut du fichier? Je n'ai rien trouvé sur le projet de démarque .

Je crois que toutes les solutions précédemment proposées (à l'exception de celles qui nécessitent des implémentations spécifiques) entraînent l'inclusion des commentaires dans le code HTML de sortie, même s'ils ne sont pas affichés.

Si vous voulez un commentaire strictement pour vous (les lecteurs du document converti ne devraient pas pouvoir le voir, même avec "voir la source"), vous pouvez (ab) utiliser les étiquettes de lien (à utiliser avec les liens de style de référence) qui sont disponible dans la spécification de base Markdown:

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

C'est:

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

Ou vous pouvez aller plus loin:

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

Pour améliorer la compatibilité de la plateforme (et pour enregistrer une frappe), il est également possible d'utiliser #(qui est une cible de lien hypertexte légitime) au lieu de <>:

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

Pour une portabilité maximale, il est important d'insérer une ligne vierge avant et après ce type de commentaires, car certains analyseurs Markdown ne fonctionnent pas correctement lorsque les définitions se rapprochent du texte normal. La recherche la plus récente avec Babelmark montre que les lignes vierges avant et après sont toutes deux importantes. Certains analyseurs afficheront le commentaire s'il n'y a pas de ligne vide avant, et certains analyseurs excluront la ligne suivante s'il n'y a pas de ligne vide après.

En général, cette approche devrait fonctionner avec la plupart des analyseurs Markdown, car elle fait partie de la spécification principale. (même si le comportement lorsque plusieurs liens sont définis, ou lorsqu'un lien est défini mais jamais utilisé, n'est pas strictement spécifié).

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. Plus d'informations sont disponibles sur le groupe de discussion pandoc .

Cette petite recherche prouve et affine 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. Utilisation #(et non <>)
2. Avec une ligne vide avant le commentaire . Une ligne vide après le commentaire n'a aucun impact sur le résultat.

La spécification Markdown stricte CommonMark ne fonctionne que comme prévu avec cette syntaxe (et non avec <>et / ou une ligne vide)

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

( +- a réussi le test, -- n'a pas réussi, ?- laisse des déchets qui ne sont pas affichés en HTML rendu).

• Pas de lignes vides, en utilisant<> 13+, 15-
• Ligne vide avant le commentaire, en utilisant<> 20+, 8-
• Lignes vides autour du commentaire, en utilisant<> 20+, 8-
• Pas de lignes vides, en utilisant# 13+ 1? 14-
• Ligne vide avant le commentaire, en utilisant # 23+ 1? 4-
• Des lignes vides autour du commentaire, en utilisant# 23+ 1? 4-
• Commentaire HTML avec 3 tirets 1+ 2? 25- de la réponse du chl (notez qu'il s'agit d'une syntaxe différente)

Cela prouve les déclarations ci-dessus.

Ces implémentations échouent aux 7 tests. Il n'y a aucune chance d'utiliser des commentaires exclus sur le rendu avec eux.

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

Si vous utilisez Jekyll ou Octopress, cela fonctionnera également.

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

Les balises Liquid {% comment %}sont analysées en premier et supprimées avant même que le processeur MarkDown n'y arrive. Les visiteurs ne verront pas lorsqu'ils essaieront d'afficher la source à partir de leur navigateur.

Une alternative consiste à placer des commentaires dans des balises HTML stylisées. De cette façon, vous pouvez basculer leur visibilité selon vos besoins. Par exemple, définissez une classe de commentaires dans votre feuille de style CSS.

.comment { display: none; }

Ensuite, 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 code HTML résultant ressemble à ceci:

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

Ce qui est essentiellement un lien vide. Évidemment, vous pouvez lire cela dans la source du texte rendu, mais vous pouvez quand même le faire sur GitHub.

Les utilisateurs de Vim Instant-Markdown doivent utiliser

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

Voir également Critic Markup, pris en charge par un nombre croissant d'outils 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 placer les commentaires dans un bloc R sans eval et sans écho? c'est à dire,

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

Semble bien fonctionner pour moi.

Divulgation: j'ai écrit le plugin.

Étant donné que la question ne spécifie pas une implémentation de démarque spécifique, je voudrais 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 apparaissaient toujours en html. Les éléments suivants ont fonctionné:

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

Utilisez ensuite l'extension + note de bas de page. Il s'agit essentiellement d'une note de bas de page qui n'est jamais référencée.

Ce qui suit fonctionne très bien

<empty line>
[whatever comment text]::

cette méthode tire parti de la syntaxe pour créer des liens via une référence
car la référence de lien créée avec [1]: http://example.orgne sera pas rendue, de même aucun des éléments suivants ne sera également rendu

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

Pour pandoc, un bon moyen de bloquer les commentaires est d'utiliser un métabloc yaml, comme suggéré par l'auteur du pandoc . J'ai remarqué que cela donne une syntaxe plus appropriée mise en évidence des commentaires par rapport à la plupart des autres solutions proposées, au moins dans mon environnement ( vim, vim-pandocet vim-pandoc-syntax).

J'utilise les commentaires de bloc yaml en combinaison avec les commentaires html-inline, car les commentaires html ne peuvent pas être imbriqués . Malheureusement, il n'y a aucun moyen de bloquer les commentaires dans le métablock yaml , donc chaque ligne doit être commentée individuellement. Heureusement, il ne devrait y avoir qu'une seule ligne dans un paragraphe enveloppé.

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 ,ma <Leader>touche, donc ,bet ,vcommente et commente un paragraphe, respectivement. Si j'ai besoin de commenter plusieurs paragraphes, je mappe j,bà une macro (généralement Q) et je lance <number-of-paragraphs><name-of-macro>(par exemple ( 3Q). La même chose fonctionne pour la décommentation.

kramdown - le moteur de démarque basé sur Ruby qui est la valeur par défaut pour Jekyll et donc GitHub Pages - a une prise en charge intégrée des commentaires via 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{:/}

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

Tu peux essayer

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

Vous pouvez le faire (bloc YAML):

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

J'ai essayé avec une sortie en latex uniquement, veuillez confirmer pour les autres.