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 .
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 .
Réponses:
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é).
[//]: # "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.
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:
#
(et non <>
)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).
<>
13+, 15-<>
20+, 8-<>
20+, 8-#
13+ 1? 14-#
23+ 1? 4-#
23+ 1? 4-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.
#
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.
#
le 21 janvier 2016. Cebe ne le gère toujours pas.
(...)
par lui-même, il le casse. Au moins sur Visual Studio Code 1.19.
%s/^\(.*\)$/[comment]: # (\1)/g
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.
{#
commentaires multilignes ici#}
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.
some text [](hidden text) blah blah
.
[](Comment text goes here)
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.
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.
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!
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.org
ne sera pas rendue, de même aucun des éléments suivants ne sera également rendu
<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever
pandoc
aussi bien pour les instances en ligne actuelles de Gitlab et GitHub .
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-pandoc
et 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 ,b
et ,v
commente 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.
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.