Commentaires dans Markdown
Quelle est la syntaxe pour stocker un commentaire dans un fichier de démarques, par ex. un commentaire CVS $ Id $ en haut du fichier? Je n'ai rien trouvé sur le projet de démarque .
Je pense que toutes les solutions proposées précédemment (à 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 qui est 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 (pour une utilisation avec des liens de style de référence): 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 pourriez aller plus loin:
[//]: <> (This is also a comment.)
Pour améliorer la compatibilité de la plate-forme (et 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 syntaxiques de Markdown ne fonctionnent pas correctement lorsque les définitions se rapprochent du texte normal. Les recherches les plus récentes sur Babelmark montrent que les lignes vides avant et après sont toutes deux importantes. Certains analyseurs afficheront le commentaire s’il n’ya pas de ligne vierge avant et d’autres excluront la ligne suivante s’il n’ya pas de ligne vierge après.
En général, cette approche devrait fonctionner avec la plupart des analyseurs syntaxiques Markdown, car elle fait partie de la spécification de base. (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 que cela fonctionne avec pandoc lors de la génération d'une sortie TeX ou HTML. Plus d'informations sont disponibles sur le groupe pandoc-discussion .
Cette petite recherche prouve et affine la réponse de Magnus
La syntaxe la plus indépendante de la plate-forme est
(empty line)
[comment]: # (This actually is the most platform independent comment)
Les deux conditions sont importantes:
- Utilisation de
#(et non de<>) - 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 de Markdown stricte CommonMark ne fonctionne comme prévu qu'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 du code source particulier dans 28 implémentations de Markdown.
(+ - a réussi le test, - - n'a pas réussi, ? - laisse des ordures non affichées dans le code HTML.).
- 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- - Lignes vides autour du commentaire, en utilisant
#23+ 1? 4- - commentaire HTML avec 3 traits d'union 1+ 2? 25- du réponse de 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-rendus 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, cela fonctionnera également.
{% comment %}
These commments will not include inside the source.
{% endcomment %}
Les balises Liquid {% comment %} sont d'abord analysées et supprimées avant même que le processeur MarkDown ne les atteigne. Les visiteurs ne verront pas lorsqu'ils essaieront de voir la source depuis leur navigateur.
Une alternative consiste à insérer des commentaires dans des balises HTML stylisées. De cette façon, vous pouvez basculer leur visibilité au besoin. 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 HTML résultant ressemble à:
<a href="Comment%20text%20goes%20here"></a>
Ce qui est fondamentalement un lien vide. Évidemment, vous pouvez lire cela dans la source du texte rendu, mais vous pouvez le faire sur GitHub de toute façon.
Voir également Critic Markup, pris en charge par un nombre croissant d’outils de Markdown.
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.
Vim Instant-Markdown les utilisateurs doivent utiliser
<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->
Que diriez-vous de mettre les commentaires dans un bloc R non-eval, non-echo? 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 une implémentation de démarquage spécifique, je voudrais mentionner le Commentaires Plugin 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 sont encore apparus en html. Ce qui suit a fonctionné:
Blank line
[^Comment]: Text that will not appear in html source
Blank line
Ensuite, utilisez l'extension + note de bas de page. C'est essentiellement une note de bas de page qui n'est jamais référencée.
Pour pandoc, un bon moyen de bloquer les commentaires est d'utiliser un yaml metablock, comme suggéré par l'auteur de pandoc . J'ai remarqué que cela permettait une mise en évidence syntaxique plus appropriée des commentaires par rapport à de nombreuses autres solutions proposées, du moins dans mon environnement (vim, vim-pandoc et vim-pandoc-syntax).
J'utilise les commentaires de bloc yaml en combinaison avec les commentaires html-inline, puisque les commentaires html ne peuvent pas être imbriqués . Malheureusement, il y a aucun moyen de bloquer les commentaires dans le yaml metablock , chaque ligne doit donc être commentée individuellement. Heureusement, il ne devrait y avoir qu'une seule ligne dans un paragraphe souple.
Dans mon ~/.vimrc, j'ai configuré 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 clé <Leader>-, donc ,b et ,v commentent et décommentent un paragraphe, respectivement. Si je dois commenter plusieurs paragraphes, je mappe j,b à une macro (généralement Q) et exécute <number-of-paragraphs><name-of-macro> (par exemple (3Q).) Même chose pour commenter.
kramdown - le moteur de démarquage basé sur Ruby qui est le moteur par défaut de Jekyll et donc de GitHub Pages -- prend en charge les commentaires intégrés 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 présente l'avantage de permettre les commentaires en ligne, mais l'inconvénient de ne pas être transférables vers d'autres moteurs Markdown.
Tu peux essayer
[](
Your comments go here however you cannot leave
// a blank line so fill blank lines with
//
Something
)
Ce qui suit fonctionne très bien
<empty line>
[whatever comment text]::
cette méthode tire parti de syntaxe pour créer des liens via référence
étant donné que la référence de lien créée avec [1]: http://example.org ne sera pas restituée, de même que les éléments suivants ne seront pas restitués
<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever
Vous pouvez faire ceci (bloc YAML):
~~~
# This is a
# multiline
# comment
...
J'ai essayé avec une sortie latex uniquement, veuillez confirmer pour les autres.
Github LISEZMOI.md OR Stackoverflow répond
Pour Github README ou Stackoverflow, j’utilise # pour commentaire en ligne.
Exemple:
# clone the remote repository to your local machine
npm clone https://github.com/chebaby/echebaby.git
# change directory
cd echebaby
# install dependencies
yarn install