Komentarze w Markdown

1399

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 .

Betamos
źródło
10
Czytając między wierszami, wydaje się, że chcesz dołączyć metadane do swojego Markdown. Z tego powodu sugerowałbym użycie preprocesora, który pozwala dodać nagłówek. Na przykład zobacz Przednią materię Jekylla . W innym przykładzie zobacz, jak Basho używa Middleman do swojej dokumentacji . (Uwaga: nie jest to bezpośrednia odpowiedź na pytanie, dlatego udostępniam go jako komentarz).
David J.
2
Zobacz także, jak MultiMarkdown obsługuje metadane .
David J.
Oto punkt odniesienia dla różnych typów komentarzy z różnymi parserami w Babelmark .
Ulysse BN

Odpowiedzi:

1452

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

Magnus
źródło
145
[//]: # "Comment"i [//]: # (Comment)wydaje się, że działa na szerszej gamie implementacji, ponieważ #jest to prawidłowy względny identyfikator URI. Na przykład GitHub odrzuca <>, a cała linia staje się widoczna. Warto również zauważyć, że etykiety linków często muszą być oddzielone od innych treści pustą linią.
Zenexer
6
Aby być najbardziej niezależnym od platformy, potrzebuje także pustej linii przed komentarzem. Zobacz testy: stackoverflow.com/a/32190021/2790048
Nick Volynkin
6
Czy można tego użyć do komentarzy wielowierszowych?
crypdick
4
@RovingRichard Tak, przynajmniej w Pandoc działa to w przypadku komentarzy wielowierszowych, jeśli w komentowanym bloku nie ma pustych linii (podział pojedynczej linii jest w porządku). Używam podejścia Magnusa do komentowania bloków i metody HTML chl do komentarzy śródliniowych (chociaż zwykle tylko 2 myślniki). W ten sposób mogę zablokować komentowanie akapitów zawierających już wbudowane komentarze HTML.
joelostblom
4
Tylko FYI, ale jeśli tworzysz spis treści za pomocą Pandoc, wygeneruje to ostrzeżenie o powielonych odnośnikach do linków. (To tylko ostrzeżenia, TOC nadal będzie tworzony.)
Karl Giesing,
995

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 .

chl
źródło
73
Jeśli dobrze rozumiem, potrójne myślniki powodują, że pandoc ignoruje komentarz podczas analizy pliku przeceny. Ale jeśli użyjesz innego silnika Markdown, komentarz pokaże się w wygenerowanym HTML (i tym samym będzie widoczny w „źródle widoku”). Musisz więc uważać na to, co umieściłeś w tym komentarzu;)
cberzan
5
Czy możesz wyjaśnić, w jaki sposób Pandoc traktuje potrójne kreski inaczej niż podwójny? Kiedy eksperymentowałem z nimi, wyglądało to tak samo. Ponadto instrukcja użytkownika Pandoc mówi „Surowy HTML jest przekazywany w niezmienionej postaci w formacie HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown i Textile, i tłumiony w innych formatach”. Potrójne kreski nie wydają się mieć większych przywilejów niż podwójne.
dkim
1
@dkim Komentarze z potrójnym myślnikiem są ignorowane i odrzucane z danych wyjściowych HTML. Nie dzieje się tak w przypadku komentarzy z podwójnymi kreskami, które są wstawiane do pliku HTML. Tak jest nadal w przypadku najnowszej wersji Pandoc (1.10).
chl
32
Jeśli potrójne myślenie jest znaczące, to nie są to „standardowe komentarze HTML”.
tripleee
17
Uwaga dla Googlersów: to niestety nie działa w GitHub Markdown, a skończyło się na rozwiązaniu Magnusa.
Daniel Buckmaster
197

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

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)
Nick Volynkin
źródło
3
Doskonałe, dokładne narzędzie do testowania! Wygląda na to, że masz rację, że # działa dla wszystkich oprócz GFM i <> działa dla GFM, ale nie dla kilku innych. Szkoda, że ​​GFM to zarówno narożnik, jak i bardzo popularny smak.
płyty kuchenne
1
Wygląda na to, że s9e \ TextFormatter współpracuje z # 21 stycznia 2016 r. Cebe nadal go nie obsługuje.
Troy Daniels
1
O dziwo, jeśli komentarz (...)sam w sobie zawiera , łamie go. Przynajmniej w Visual Studio Code 1.19.
Royi
1
i tym samym dla użytkowników vim, którzy chcą skomentować cały plik na raz:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.
Co to mówi o przecenie, że Bablemark2 istnieje?
TC Proctor
53

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.

uiroshan
źródło
2
Jinja2 = {#tutaj komentarze wielowierszowe#}
John Mee
29

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

Stu
źródło
5
Kopiowanie / wklejanie prawdopodobnie zakończy się kopiowaniem „skomentowanego” tekstu, a także zwykłego tekstu, dlatego należy zachować ostrożność podczas korzystania z niego. Może łatwo wygenerować nieoczekiwane wyniki dla osoby kopiującej blok tekstu.
Eilon
4
@Eilon również dostępność tego byłaby straszna
Ethan
Silniki wspierające dostępność będą poprawnie pomijać wyświetlanie: brak tekstu.
aredridel
28

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.

jomo
źródło
6
Z pewnością tak jest, ale w rzeczywistości jest to jedyna jak dotąd odpowiedź, która zawsze działa na GitHub, np. Na listach.
jomo
Doszedłem do tego samego rozwiązania. To jedyny, w którym mogę pracować dla komentarzy w linii, np some text [](hidden text) blah blah.
c24w
3
To już nie działa na github dzień 2019-03-08, renderuje jak jest[](Comment text goes here)
dogmatic69
19

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.
-->
alex
źródło
18

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.
Kerim
źródło
5
Myślę, że jednym z problemów związanych z takimi „pseudo” standardami jest to, że nie są przenośne. Na niektórych stronach działają one idealnie, na innych nie.
Willem Van Onsem
14

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.

David Kaufman
źródło
2
Ponadto, możesz swobodnie robić takie rzeczy jak cat("# Some Header")w obrębie „zakomentowanych” bloków kodu i używać results = "asis", a także możesz dodawać całe skomentowane sekcje do swojego kodu, które można włączać / wyłączać przez przełączanie eval = FALSE, ponieważ ocena R jest wykonywana przed kompilacja pandoc. Dzięki za pomysł!
MichaelChirico,
11

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.

Ryne Everett
źródło
11
<!--- ... --> 

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.

Brad Porter
źródło
Najbardziej mi się to podoba, ponieważ w ogóle nie generuje żadnych wyników. Dla Bitbucket ten przedrostek jest wystarczająca: [#]: .
Ceving
7

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
anapsix
źródło
Ten (przetestowany pierwszy wariant) działa zarówno dla pandocbieżących instancji online Gitlab, jak i GitHub .
doak
5

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.

joelostblom
źródło
5

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.

vossad01
źródło
4

Możesz spróbować

[](
Your comments go here however you cannot leave
// a blank line so fill blank lines with
//
Something
)
magaga
źródło
4

Możesz to zrobić (blok YAML):

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

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

Flo
źródło
Działa również z danymi wyjściowymi HTML.
petzi
Nie jestem pewien, czy potwierdzenie Daniela w formacie HTML jest prawidłowe. Zrobiłem to z plikiem wyjściowym HTML i uruchomiłem „pandoc --bibliography paper.bib -o paper.html paper.md”, a HTML pokazał linie komentarzy.
markgalassi