Kommentare in Markdown

Wie lautet die Syntax zum Speichern eines Kommentars in einer Markdown-Datei, z. B. eines CVS $ Id $ -Kommentars oben in der Datei? Ich habe nichts auf dem Markdown-Projekt gefunden .

Ich glaube, dass alle zuvor vorgeschlagenen Lösungen (mit Ausnahme derjenigen, die bestimmte Implementierungen erfordern) dazu führen, dass die Kommentare in den Ausgabe-HTML-Code aufgenommen werden, auch wenn sie nicht angezeigt werden.

Wenn Sie einen Kommentar wünschen, der ausschließlich für Sie selbst bestimmt ist (Leser des konvertierten Dokuments sollten ihn selbst mit "Quelltext anzeigen" nicht sehen können), können Sie (ab) die Linkbezeichnungen (zur Verwendung mit Links im Referenzstil) verwenden verfügbar in der Kern-Markdown-Spezifikation:

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

Das ist:

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

Oder Sie könnten noch weiter gehen:

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

Um die Plattformkompatibilität zu verbessern (und einen Tastendruck zu speichern), ist es auch möglich, #(was ein legitimes Hyperlink-Ziel ist) anstelle von <>:

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

Für maximale Portabilität ist es wichtig, vor und nach dieser Art von Kommentaren eine Leerzeile einzufügen, da einige Markdown-Parser nicht richtig funktionieren, wenn Definitionen mit normalem Text verglichen werden. Die jüngsten Untersuchungen mit Babelmark zeigen, dass Leerzeilen davor und danach wichtig sind. Einige Parser geben den Kommentar aus, wenn zuvor keine Leerzeile vorhanden ist, und einige Parser schließen die folgende Zeile aus, wenn danach keine Leerzeile vorhanden ist.

Im Allgemeinen sollte dieser Ansatz mit den meisten Markdown-Parsern funktionieren, da er Teil der Kernspezifikation ist. (Auch wenn das Verhalten, wenn mehrere Links definiert sind oder wenn ein Link definiert, aber nie verwendet wird, nicht genau angegeben ist).

Ich verwende Standard-HTML-Tags wie

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

Beachten Sie den dreifachen Strich. Der Vorteil ist, dass es beim Generieren von TeX- oder HTML-Ausgaben mit Pandoc funktioniert . Weitere Informationen finden Sie in der Pandoc-Diskussionsgruppe .

Diese kleine Forschung beweist und verfeinert die Antwort von Magnus

Die plattformunabhängigste Syntax ist

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

Beide Bedingungen sind wichtig:

1. Verwenden #(und nicht <>)
2. Mit einer leeren Zeile vor dem Kommentar . Eine leere Zeile nach dem Kommentar hat keinen Einfluss auf das Ergebnis.

Die strenge Markdown-Spezifikation CommonMark funktioniert nur wie vorgesehen mit dieser Syntax (und nicht mit <>und / oder einer Leerzeile).

Um dies zu beweisen, verwenden wir das Babelmark2 von John MacFarlane. Dieses Tool überprüft das Rendern eines bestimmten Quellcodes in 28 Markdown-Implementierungen.

( +- hat den Test bestanden, -- hat nicht bestanden, ?- hinterlässt Müll, der in gerendertem HTML nicht angezeigt wird).

• Keine leeren Zeilen mit<> 13+, 15-
• Leere Zeile vor dem Kommentar mit<> 20+, 8-
• Leere Zeilen um den Kommentar mit<> 20+, 8-
• Keine leeren Zeilen mit# 13+ 1? 14-
• Leere Zeile vor dem Kommentar mit # 23+ 1? 4-
• Leere Zeilen um den Kommentar mit# 23+ 1? 4-
• HTML-Kommentar mit 3 Bindestrichen 1+ 2? 25- aus der Antwort des Chl (beachten Sie, dass dies eine andere Syntax ist)

Dies beweist die obigen Aussagen.

Diese Implementierungen schlagen alle 7 Tests fehl. Es gibt keine Möglichkeit, ausgeschlossene Kommentare beim Rendern mit ihnen zu verwenden.

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

Wenn Sie Jekyll oder Octopress verwenden, funktioniert das Folgende ebenfalls.

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

Die Liquid-Tags {% comment %}werden zuerst analysiert und entfernt, bevor der MarkDown-Prozessor überhaupt darauf zugreift. Besucher werden nicht sehen, wenn sie versuchen, die Quelle in ihrem Browser anzuzeigen.

Eine Alternative besteht darin, Kommentare in stilisierte HTML-Tags einzufügen. Auf diese Weise können Sie die Sichtbarkeit nach Bedarf umschalten. Definieren Sie beispielsweise eine Kommentarklasse in Ihrem CSS-Stylesheet.

.comment { display: none; }

Dann das folgende erweiterte MARKDOWN

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

erscheint in einem BROWSER wie folgt

We do support comments

Dies funktioniert auf GitHub:

[](Comment text goes here)

Das resultierende HTML sieht aus wie folgt:

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

Welches ist im Grunde ein leerer Link. Natürlich können Sie das in der Quelle des gerenderten Textes lesen, aber Sie können das trotzdem auf GitHub tun.

Vim Instant-Markdown- Benutzer müssen verwenden

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

Siehe auch Critic Markup, das von einer zunehmenden Anzahl von Markdown-Tools unterstützt wird.

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.

Wie wäre es, wenn Sie die Kommentare in einen R-Block ohne Auswertung und ohne Echo einfügen? dh

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

Scheint gut für mich zu funktionieren.

Offenlegung: Ich habe das Plugin geschrieben.

Da in der Frage keine bestimmte Markdown-Implementierung angegeben ist, möchte ich das Kommentar-Plugin für Python-Markdown erwähnen , das denselben oben erwähnten Pandoc-Kommentierungsstil implementiert.

<!--- ... --> 

Funktioniert nicht in Pandoc Markdown (Pandoc 1.12.2.1). Kommentare erschienen immer noch in HTML. Folgendes hat funktioniert:

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

Verwenden Sie dann die + Fußnotenerweiterung. Es ist im Wesentlichen eine Fußnote, auf die nie verwiesen wird.

Das Folgende funktioniert sehr gut

<empty line>
[whatever comment text]::

Diese Methode nutzt die Syntax, um Links über eine Referenz zu erstellen,
da die mit erstellte [1]: http://example.orgLinkreferenz nicht gerendert wird. Ebenso wird auch keine der folgenden Methoden gerendert

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

Für Pandoc ist es eine gute Möglichkeit, Kommentare zu blockieren, einen Yaml-Metablock zu verwenden, wie vom Pandoc-Autor vorgeschlagen . Ich habe bemerkt , dass dies die richtige Syntax - Hervorhebung der Kommentare gibt im Vergleich zu vielen anderen Lösungen vorgeschlagen, zumindest in meiner Umgebung ( vim, vim-pandoc, und vim-pandoc-syntax).

Ich verwende Yaml-Blockkommentare in Kombination mit HTML-Inline-Kommentaren, da HTML-Kommentare nicht verschachtelt werden können . Leider gibt es keine Möglichkeit, Kommentare innerhalb des yaml-Metablocks zu blockieren , sodass jede Zeile einzeln kommentiert werden muss. Glücklicherweise sollte ein Softwrapped-Absatz nur eine Zeile enthalten.

In meinem habe ~/.vimrcich benutzerdefinierte Verknüpfungen für Blockkommentare eingerichtet:

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

Ich benutze ,als <Leader>-key, also ,bund ,vkommentiere bzw. kommentiere einen Absatz. Wenn ich mehrere Absätze kommentieren muss, ordne ich j,b(normalerweise Q) einem Makro zu und führe es aus <number-of-paragraphs><name-of-macro>(z 3Q. B. ( ). Dasselbe gilt für das Kommentieren von Kommentaren .

kramdown - die Ruby-basierte Markdown-Engine, die die Standardeinstellung für Jekyll und damit für GitHub Pages ist - verfügt über eine integrierte Kommentarunterstützung durch die Erweiterungssyntax :

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

Dies hat den Vorteil, dass Inline-Kommentare zulässig sind, hat jedoch den Nachteil, dass es nicht auf andere Markdown-Engines portierbar ist.

Du kannst es versuchen

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

Sie können dies tun (YAML-Block):

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

Ich habe es nur mit Latexausgabe versucht, bitte für andere bestätigen.