it-swarm.com.de

Kommentare in Markdown

Wie lautet die Syntax zum Speichern eines Kommentars in einer Abschriftdatei, z. Einen CVS $ Id $ -Kommentar oben in der Datei? Am Abschriftenprojekt habe ich nichts gefunden.

1225
Betamos

Ich glaube, dass alle zuvor vorgeschlagenen Lösungen (mit Ausnahme derer, die bestimmte Implementierungen erfordern) dazu führen, dass die Kommentare im Ausgabe-HTML-Code enthalten sind, 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 die Link-Bezeichnungen (zur Verwendung mit Links im Referenzstil) verwenden verfügbar in der Core 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 weiter gehen:

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

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

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

Für eine 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 abgeglichen werden. Die jüngsten Untersuchungen mit Babelmark haben gezeigt, dass Leerzeichen vor und nach wichtig sind. Einige Parser geben den Kommentar aus, wenn vorher keine Leerzeile vorhanden ist, und einige Parser schließen die folgende Zeile aus, wenn nachher 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 bei der Definition mehrerer Links oder wenn ein Link definiert, aber nie verwendet wird, nicht genau festgelegt ist).

1267
Magnus

Ich verwende Standard-HTML-Tags wie

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

Beachten Sie den dreifachen Gedankenstrich. Der Vorteil ist, dass es mit pandoc funktioniert, wenn TeX- oder HTML-Ausgaben generiert werden. Weitere Informationen finden Sie in der Gruppe pandoc-discussion .

905
chl

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 von # (und nicht <>)
  2. Mit einer leeren Zeile vor dem Kommentar . Eine leere Zeile nach dem Kommentar hat keinen Einfluss auf das Ergebnis.

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

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

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

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)
172
Nick Volynkin

Wenn Sie Jekyll oder Octopress verwenden, funktioniert auch Folgendes.

{% 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, den Quellcode in ihrem Browser anzuzeigen.

51
uiroshan

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

.comment { display: none; }

Dann wird das folgende MARKDOWN verbessert

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

erscheint in einem BROWSER wie folgt

We do support comments

32
Stu

Das funktioniert auf GitHub:

[](Comment text goes here)

Das resultierende HTML sieht folgendermaßen aus:

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

29
jomo

Siehe auch Kritisches 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.
17
Kerim

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

Wie wäre es, wenn Sie die Kommentare in einen nicht auswertbaren R-Block ohne Echo schreiben? d.h.

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

Scheint für mich gut zu funktionieren.

13
David Kaufman

Offenlegung: Ich habe das Plugin geschrieben.

Da in der Frage keine bestimmte Abschriftenimplementierung angegeben ist, möchte ich das Comments Plugin für Python-Abschriften erwähnen, das denselben oben erwähnten Pandoc-Kommentarstil implementiert.

11
Ryne Everett
<!--- ... --> 

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.

9
Brad Porter

Für Pandoc ist eine gute Möglichkeit, Kommentare zu blockieren, die Verwendung eines yaml-Metablocks wie vom Pandoc-Autor vorgeschlagen . Ich habe festgestellt, dass die Kommentare dadurch syntaktisch besser hervorgehoben werden als bei vielen anderen vorgeschlagenen Lösungen, zumindest in meiner Umgebung (vim, vim-pandoc und vim-pandoc-syntax).

Ich verwende Yaml-Block-Kommentare in Kombination mit HTML-Inline-Kommentaren, da HTML-Kommentare können nicht verschachtelt werden . Leider gibt es keine Möglichkeit zum Kommentieren von Blöcken innerhalb des yaml-Metablocks , daher muss jede Zeile einzeln kommentiert werden. Glücklicherweise sollte ein umbrochener Absatz nur eine Zeile enthalten.

In meinem ~/.vimrc habe ich 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 meine <Leader>- Taste, also kommentieren ,b und ,v einen Absatz und kommentieren ihn aus. Wenn ich mehrere Absätze kommentieren muss, ordne ich j,b einem Makro zu (normalerweise Q) und führe <number-of-paragraphs><name-of-macro> aus (z. B. (3Q). Dasselbe gilt für das Auskommentieren.

5
joelostblom

kramdown - die Ruby-basierte Markdown-Engine, die standardmäßig für Jekyll und damit für GitHub Pages verwendet wird - ist integriert Kommentarunterstützung durch seine 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 sie nicht für andere Markdown-Engines portierbar sind.

5
vossad01

Du kannst es versuchen

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

Folgendes funktioniert sehr gut

<empty line>
[whatever comment text]::

diese Methode nutzt Syntax zum Erstellen von Links über Verweis
Da mit [1]: http://example.org erstellte Linkreferenzen nicht gerendert werden, wird auch keines der folgenden Elemente gerendert

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

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

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

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

1
Flo

Github README.md OR Stackoverflow-Antworten

Für Github README oder Stackoverflow-Antworten verwende ich # für Inline-Kommentar.

Beispiel:


# clone the remote repository to your local machine

npm clone https://github.com/chebaby/echebaby.git

# change directory

cd echebaby

# install dependencies

yarn install
0
chebaby