Komentarze w Markdown

Jaka jest składnia do przechowywania komentarza w pliku przeceny, np. Komentarz CVS $ Id $ u góry pliku? Nic nie znalazłem w projekcie przeceny .

Uważam, że wszystkie wcześniej zaproponowane rozwiązania (oprócz tych, które wymagają konkretnych implementacji) powodują, że komentarze są dołączane do wyjściowego kodu HTML, nawet jeśli nie są wyświetlane.

Jeśli chcesz komentarz wyłącznie dla siebie (czytelnicy przekonwertowanego dokumentu nie powinni go widzieć, nawet w „źródle widoku”), możesz (ab) użyć etykiet linków (do użycia z linkami w stylu referencyjnym), które są dostępne w podstawowej specyfikacji Markdown:

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

To jest:

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

Lub możesz pójść dalej:

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

Aby poprawić zgodność platformy (i zaoszczędzić jedno naciśnięcie klawisza), można również użyć #(który jest uzasadnionym celem hiperłącza) zamiast <>:

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

Aby zapewnić maksymalną przenośność, ważne jest wstawienie pustego wiersza przed i po komentarzach tego typu, ponieważ niektóre parsery Markdown nie działają poprawnie, gdy definicje odrywają się od zwykłego tekstu. Najnowsze badania z Babelmark pokazują, że puste linie przed i po są ważne. Niektóre parsery wypiszą komentarz, jeśli wcześniej nie było pustej linii, a niektóre parsery wykluczą następną linię, jeśli po niej nie będzie pustej linii.

Ogólnie rzecz biorąc, to podejście powinno działać z większością parserów Markdown, ponieważ jest to część podstawowej specyfikacji. (nawet jeśli zachowanie, gdy zdefiniowano wiele łączy lub gdy łącze jest zdefiniowane, ale nigdy nie jest używane, nie jest ściśle określone).

Używam standardowych tagów HTML, takich jak

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

Zwróć uwagę na potrójną kreskę. Zaletą jest to, że działa z pandoc podczas generowania danych wyjściowych TeX lub HTML. Więcej informacji jest dostępnych w grupie dyskusyjnej pandoc .

To małe badanie potwierdza i udoskonala odpowiedź Magnusa

Najbardziej niezależna od platformy składnia to

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

Oba warunki są ważne:

1. Używanie #(i nie <>)
2. Z pustą linią przed komentarzem . Pusta linia po komentarzu nie ma wpływu na wynik.

Ścisła specyfikacja Markdown CommonMark działa tylko zgodnie z przeznaczeniem z tą składnią (a nie z <>i / lub pustą linią)

Aby to udowodnić, użyjemy Babelmark2, napisanego przez Johna MacFarlane'a. To narzędzie sprawdza rendering konkretnego kodu źródłowego w 28 implementacjach Markdown.

( +- zdał test, -- nie zdał, ?- pozostawia śmieci, które nie są wyświetlane w renderowanym HTML).

• Bez pustych linii, używając<> 13+, 15-
• Pusty wiersz przed komentarzem, używając<> 20+, 8-
• Puste wiersze wokół komentarza, przy użyciu<> 20+, 8-
• Brak pustych linii przy użyciu# 13+ 1? 14
• Pusta linia przed komentarzem, używając # 23+ 1? 4-
• Puste linie wokół komentarza, używając# 23+ 1? 4-
• Komentarz HTML z 3 myślnikami 1+ 2? 25- od odpowiedzi chl (zauważ, że to inna składnia)

To potwierdza powyższe stwierdzenia.

Te implementacje kończą się niepowodzeniem we wszystkich 7 testach. Nie ma szans na użycie z nimi komentarzy wykluczonych przy renderowaniu.

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

Jeśli używasz Jekyll lub octopress, następujące działania również będą działać.

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

Tagi Liquid {% comment %}są najpierw analizowane i usuwane, zanim procesor MarkDown do nich dojdzie. Odwiedzający nie zobaczą, gdy spróbują wyświetlić źródło z przeglądarki.

Alternatywą jest umieszczanie komentarzy w stylizowanych znacznikach HTML. W ten sposób możesz w razie potrzeby przełączać ich widoczność. Na przykład zdefiniuj klasę komentarzy w arkuszu stylów CSS.

.comment { display: none; }

Następnie następujące ulepszone MARKDOWN

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

pojawia się w PRZEGLĄDARCE w następujący sposób

We do support comments

Działa to na GitHub:

[](Comment text goes here)

Powstały HTML wygląda następująco:

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

Co jest w zasadzie pustym linkiem. Oczywiście możesz to przeczytać w źródle renderowanego tekstu, ale możesz to zrobić w GitHub.

Użytkownicy Vim Instant-Markdown muszą korzystać

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

Zobacz także Critic Markup, wspierany przez rosnącą liczbę narzędzi 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.

Co powiesz na umieszczenie komentarzy w nie-ewaluacyjnym, bez echa bloku R? to znaczy,

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

Wydaje się, że działa dobrze dla mnie.

Ujawnienie: Napisałem wtyczkę.

Ponieważ pytanie nie określa konkretnej implementacji Markdown, chciałbym wspomnieć o wtyczce Komentarze dla python-markdown , która implementuje ten sam styl komentowania pandoc, o którym mowa powyżej.

<!--- ... --> 

Nie działa w Pandoc Markdown (Pandoc 1.12.2.1). Komentarze wciąż pojawiały się w html. Następujące działało:

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

Następnie użyj rozszerzenia + przypisu dolnego. Jest to zasadniczo przypis, do którego nigdy się nie odwołujemy.

Poniższe działa bardzo dobrze

<empty line>
[whatever comment text]::

ta metoda korzysta ze składni do tworzenia linków poprzez referencje,
ponieważ referencje do linków utworzone za pomocą [1]: http://example.orgnie będą renderowane, podobnie jak żadne z poniższych

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

W przypadku pandoc dobrym sposobem na zablokowanie komentarza jest użycie metamocka yaml, zgodnie z sugestią autora pandoc . Zauważyłem, że daje to bardziej właściwe podświetlanie składni komentarzach w porównaniu do wielu innych proponowanych rozwiązań, przynajmniej w moim otoczeniu ( vim, vim-pandoc, i vim-pandoc-syntax).

Używam komentarzy blokujących yaml w połączeniu z komentarzami HTML , ponieważ nie można zagnieżdżać komentarzy HTML . Niestety nie ma sposobu na blokowanie komentowania w metameczce yaml , więc każda linia musi być komentowana indywidualnie. Na szczęście powinna być tylko jedna linia w akapicie z miękkim zapisem.

W moim ~/.vimrcustawiłem niestandardowe skróty do blokowania komentarzy:

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

Używam ,jako mój <Leader>klawiszem, więc ,bi ,vkomentarz i usuń paragraf odpowiednio. Jeśli muszę skomentować wiele akapitów, odwzorowuję j,bmakro (zwykle Q) i uruchamiam <number-of-paragraphs><name-of-macro>(np. ( 3Q). To samo działa w przypadku odkomentowania.

kramdown - oparty na Ruby silnik markdown, który jest domyślny dla Jekyll, a tym samym GitHub Pages - ma wbudowaną obsługę komentarzy dzięki składni rozszerzenia :

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

Ma to tę zaletę, że pozwala na komentarze w linii, ale wadą jest brak możliwości przenoszenia na inne silniki Markdown.

Możesz spróbować

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

Możesz to zrobić (blok YAML):

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

Próbowałem tylko z wyjściem lateksowym, proszę potwierdzić dla innych.