Commentaires dans Markdown


1402

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 .


10
En lisant entre les lignes, il semble que vous souhaitiez joindre des métadonnées à votre Markdown. Pour cette raison, je suggère d'utiliser un préprocesseur qui vous permet d'ajouter un en-tête. Pour un exemple, voir Front Matter de Jekyll . Pour un autre exemple, voyez comment Basho utilise Middleman pour sa documentation . (Remarque: Ce n'est pas une réponse directe à la question, c'est pourquoi je la partage en tant que commentaire.)
David J.


Voici une référence de différents types de commentaires avec différents analyseurs sur Babelmark .
Ulysse BN

Réponses:


1457

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


145
[//]: # "Comment"et [//]: # (Comment)semblent fonctionner sur une plus grande variété d'implémentations, car il #s'agit d'un URI relatif valide. GitHub, par exemple, rejette <>et toute la ligne devient visible. Il convient également de noter que les étiquettes de lien doivent souvent être séparées des autres contenus par une ligne vierge.
Zenexer

6
Pour être le plus indépendant de la plateforme, il a également besoin d'une ligne vide avant le commentaire. Voir les tests: stackoverflow.com/a/32190021/2790048
Nick Volynkin

6
Peut-il être utilisé pour des commentaires multilignes?
crypdick

4
@RovingRichard Oui, au moins dans Pandoc, cela fonctionne pour les commentaires multilignes s'il n'y a pas de lignes vides dans le bloc commenté (les sauts de ligne simples sont très bien). J'utilise l'approche de Magnus pour les commentaires de bloc et l'approche HTML de chl pour les commentaires en ligne (bien que généralement seulement 2 tirets). De cette façon, je peux bloquer les paragraphes de commentaires contenant déjà des commentaires HTML en ligne.
joelostblom

4
Juste pour info, mais si vous créez une table des matières à l'aide de Pandoc, cela générera un avertissement concernant les références de lien en double. (Ce ne sont que des avertissements, la table des matières sera toujours créée.)
Karl Giesing

996

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 .


73
Si je comprends bien, le triple tiret fait que pandoc ignore le commentaire lorsqu'il analyse le fichier de démarque. Mais si vous utilisez un autre moteur de démarque, le commentaire apparaîtra dans le code HTML généré (et sera donc visible avec "view source"). Vous devez donc faire attention à ce que vous mettez dans ce commentaire;)
cberzan

5
Pouvez-vous expliquer comment Pandoc traite les tirets triples différemment des tirets doubles? Quand je les ai expérimentés, ils semblaient être traités de la même manière. En outre, le guide de l'utilisateur Pandoc dit simplement "Le HTML brut est transmis sans modification dans les sorties HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown et Textile, et supprimé dans d'autres formats." Les tirets triples ne semblent pas avoir de privilège plus élevé que les tirets doubles.
dkim

1
@dkim Les commentaires avec un triple tiret sont ignorés et ignorés de la sortie HTML. Ce n'est pas le cas des commentaires à double tiret qui sont insérés dans le fichier HTML. C'est toujours le cas avec la dernière version de Pandoc (1.10).
chl

32
Si le triple tiret est significatif, il ne s'agit pas de commentaires "HTML standard".
tripleee

17
Remarque pour les Googleurs: cela ne fonctionne malheureusement pas dans GitHub Markdown, et j'ai fini par utiliser la solution de Magnus.
Daniel Buckmaster,

198

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

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)

3
Excellent outil de test complet! Il semble que vous ayez raison qui # fonctionne pour tous sauf GFM et <> fonctionne pour GFM mais pas pour quelques autres. Dommage que GFM soit à la fois un cas d'angle et aussi une saveur très populaire.
plaques de cuisson

1
Il semble que s9e \ TextFormatter fonctionne avec # le 21 janvier 2016. Cebe ne le gère toujours pas.
Troy Daniels

1
Étrangement, si le commentaire contient (...)par lui-même, il le casse. Au moins sur Visual Studio Code 1.19.
Royi

1
et donc pour les utilisateurs de vim qui veulent commenter tout un fichier à la fois:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.

Que dit-il au sujet du démarque que Bablemark2 existe?
TC Proctor

55

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.


2
Jinja2 = {#commentaires multilignes ici#}
John Mee

29

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


5
Le copier / coller finira probablement par copier le texte "commenté" ainsi que le texte normal, donc soyez prudent lorsque vous l'utilisez. Cela pourrait facilement produire des résultats inattendus pour quelqu'un qui copie un bloc de texte.
Eilon

4
@Eilon aussi l'accessibilité serait terrible
Ethan

Les moteurs prenant en charge l'accessibilité ignoreront correctement l'affichage: aucun texte.
aredridel

28

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.


6
C'est certainement le cas, mais c'est en fait la seule réponse à ce jour qui fonctionne toujours sur GitHub, par exemple dans les listes.
jomo

Je suis arrivé à la même solution. C'est le seul que je puisse obtenir pour les commentaires en ligne, par exemple some text [](hidden text) blah blah.
c24w

3
Cela ne fonctionne plus sur github à partir du 2019-03-08, il s'affiche tel quel[](Comment text goes here)
dogmatic69

19

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

18

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.

5
Je pense que l'un des problèmes avec ces normes "pseudo" est qu'elles ne sont pas portables. Sur certains sites Web, ceux-ci fonctionneront parfaitement, sur d'autres, ils ne fonctionneront pas.
Willem Van Onsem du

14

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.


2
Aussi, n'hésitez pas à faire des choses comme cat("# Some Header")dans les blocs de code "commentés" et à utiliser results = "asis", et vous pouvez ajouter des sections entières commentées à votre code qui peuvent être activées / désactivées en basculant eval = FALSE, puisque l'évaluation R est effectuée avant le compilation pandoc. Merci pour l'idée!
MichaelChirico

11

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.


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

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.


Je préfère cela, car il ne génère aucune sortie. Pour Bitbucket ce préfixe est suffisant: [#]: .
ceving

7

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

Cette (première variante testée) fonctionne pandocaussi bien pour les instances en ligne actuelles de Gitlab et GitHub .
doak

5

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.


5

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.


4

Tu peux essayer

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

4

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.


Il fonctionne également avec la sortie HTML.
petzi

Je ne sais pas si la confirmation de Daniel de la sortie html est correcte. Je l'ai fait avec un fichier de sortie html et j'ai exécuté "pandoc --bibliography paper.bib -o paper.html paper.md" et le code HTML montrait les lignes de commentaire.
Markgalassi
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.