Komentar dalam penurunan harga

1402

Apa sintaksis untuk menyimpan komentar dalam file penurunan harga, misalnya komentar $ Id $ CVS di bagian atas file? Saya tidak menemukan apa pun di proyek penurunan harga .

Betamo
sumber
10
Membaca yang tersirat, sepertinya Anda ingin melampirkan metadata ke penurunan harga Anda. Untuk alasan itu, saya sarankan menggunakan preprocessor yang memungkinkan Anda menambahkan header. Misalnya, lihat Jekyll's Front Matter . Untuk contoh lain, lihat bagaimana Basho menggunakan Middleman untuk dokumentasi mereka . (Catatan: Ini bukan jawaban langsung untuk pertanyaan itu, itulah sebabnya saya membagikannya sebagai komentar.)
David J.
2
Lihat juga bagaimana MultiMarkdown mendukung metadata .
David J.
Berikut adalah patokan dari berbagai jenis komentar dengan parser yang berbeda di Babelmark .
Ulysse BN

Jawaban:

1456

Saya percaya bahwa semua solusi yang diusulkan sebelumnya (selain dari yang membutuhkan implementasi spesifik) menghasilkan komentar yang dimasukkan dalam output HTML, bahkan jika mereka tidak ditampilkan.

Jika Anda menginginkan komentar yang hanya untuk Anda sendiri (pembaca dokumen yang dikonversi tidak dapat melihatnya, bahkan dengan "sumber tampilan") Anda dapat (ab) menggunakan label tautan (untuk digunakan dengan tautan gaya referensi) yang tersedia dalam spesifikasi Penurunan harga inti:

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

Itu adalah:

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

Atau Anda bisa melangkah lebih jauh:

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

Untuk meningkatkan kompatibilitas platform (dan untuk menyimpan satu penekanan tombol) juga dimungkinkan untuk menggunakan #(yang merupakan target hyperlink yang sah) alih-alih <>:

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

Untuk portabilitas maksimum, penting untuk menyisipkan baris kosong sebelum dan sesudah jenis komentar ini, karena beberapa parser penurunan harga tidak berfungsi dengan benar ketika definisi menyapu terhadap teks biasa. Penelitian terbaru dengan Babelmark menunjukkan bahwa garis kosong sebelum dan sesudah keduanya penting. Beberapa parser akan menampilkan komentar jika tidak ada baris kosong sebelumnya, dan beberapa parser akan mengecualikan baris berikut jika tidak ada baris kosong setelahnya.

Secara umum, pendekatan ini harus bekerja dengan sebagian besar parser Markdown, karena itu adalah bagian dari spesifikasi inti. (bahkan jika perilaku ketika banyak tautan didefinisikan, atau ketika tautan didefinisikan tetapi tidak pernah digunakan, tidak ditentukan secara ketat).

Magnus
sumber
145
[//]: # "Comment"dan [//]: # (Comment)tampaknya bekerja pada berbagai implementasi yang lebih luas, karena #merupakan URI relatif yang valid. GitHub, misalnya, menolak <>, dan seluruh baris menjadi terlihat. Perlu juga dicatat bahwa label tautan sering kali harus dipisahkan dari konten lain dengan baris kosong.
Zenexer
6
Untuk menjadi yang paling independen terhadap platform, juga membutuhkan baris kosong sebelum komentar. Lihat tes: stackoverflow.com/a/32190021/2790048
Nick Volynkin
6
Apakah ini dapat digunakan untuk komentar multiline?
crypdick
4
@RovingRichard Ya, setidaknya di Pandoc ini berfungsi untuk komentar multiline jika tidak ada baris kosong di blok komentar (jeda baris tunggal baik-baik saja). Saya menggunakan pendekatan Magnus untuk komentar blok dan pendekatan HTML chl untuk komentar sebaris (walaupun biasanya hanya 2 tanda hubung). Dengan cara ini saya dapat memblokir komentar paragraf yang sudah berisi komentar HTML sebaris.
joelostblom
4
Hanya FYI, tetapi jika Anda membuat TOC menggunakan Pandoc, ini akan menghasilkan peringatan tentang referensi tautan rangkap. (Ini hanya peringatan, TOC masih akan dibuat.)
Karl Giesing
995

Saya menggunakan tag HTML standar, seperti

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

Perhatikan dasbor tiga. Keuntungannya adalah ia bekerja dengan pandoc saat menghasilkan keluaran TeX atau HTML. Informasi lebih lanjut tersedia di grup pandoc-mendiskusikan .

chl
sumber
73
Jika saya mengerti dengan benar, triple dash membuat pandoc mengabaikan komentar ketika mem-parsing file penurunan harga. Tetapi jika Anda menggunakan mesin penurunan harga lainnya, komentar AKAN muncul di HTML yang dihasilkan (dan karenanya dapat dilihat dengan "view source"). Jadi, Anda harus berhati-hati dengan komentar Anda;)
cberzan
5
Bisakah Anda jelaskan bagaimana Pandoc memperlakukan tiga garis berbeda dari garis ganda? Ketika saya bereksperimen dengan mereka, mereka tampaknya ditangani dengan cara yang sama. Juga, panduan pengguna Pandoc hanya mengatakan "HTML mentah dilewatkan tidak berubah dalam HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, dan output Tekstil, dan ditekan dalam format lain." Triple dash tampaknya tidak memiliki hak istimewa yang lebih tinggi daripada yang ganda.
dkim
1
@dkim Komentar dengan triple dash diabaikan dan dibuang dari output HTML. Ini tidak terjadi dengan komentar dua arah yang dimasukkan dalam file HTML. Ini masih terjadi dengan Pandoc versi terbaru (1.10).
chl
32
Jika triple dash signifikan maka ini bukan komentar "HTML standar".
tripleee
17
Catatan untuk Googlers: sayangnya ini tidak berfungsi di GitHub Markdown, dan saya akhirnya menggunakan solusi Magnus.
Daniel Buckmaster
198

Penelitian kecil ini membuktikan dan memperbaiki jawaban oleh Magnus

Sintaksis platform paling independen adalah

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

Kedua kondisi itu penting:

  1. Menggunakan #(dan tidak <>)
  2. Dengan baris kosong sebelum komentar . Baris kosong setelah komentar tidak berdampak pada hasil.

Spesifikasi Markdown yang ketat CommonMark hanya berfungsi sebagaimana dimaksud dengan sintaks ini (dan tidak dengan <>dan / atau baris kosong)

Untuk membuktikan ini, kita akan menggunakan Babelmark2, yang ditulis oleh John MacFarlane. Alat ini memeriksa rendering kode sumber tertentu dalam 28 implementasi penurunan harga.

( +- lulus tes, -- tidak lulus, ?- meninggalkan beberapa sampah yang tidak ditampilkan dalam HTML yang diberikan).

Ini membuktikan pernyataan di atas.

Implementasi ini gagal semua 7 tes. Tidak ada kesempatan untuk menggunakan komentar yang dikecualikan saat memberikannya.

  • cebe / penurunan harga 1.1.0
  • cebe / penurunan harga MarkdownExtra 1.1.0
  • cebe / penurunan harga GFM 1.1.0
  • s9e \ TextFormatter (Fatdown / PHP)
Nick Volynkin
sumber
3
Alat pengujian yang luar biasa dan teliti! Sepertinya Anda benar yang # bekerja untuk semua kecuali GFM dan <> bekerja untuk GFM tetapi tidak untuk pasangan lain. GFM yang terlalu buruk adalah penutup dan juga rasa yang sangat populer.
Hobs
1
Sepertinya s9e \ TextFormatter bekerja # pada 21 Januari 2016. Cebe masih tidak menanganinya.
Troy Daniels
1
Anehnya, jika komentar itu berisi (...)dengan sendirinya, itu merusaknya. Setidaknya pada Visual Studio Code 1.19.
Royi
1
dan dengan demikian untuk pengguna vim yang ingin mengomentari semua file sekaligus:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.
Apa yang dikatakan tentang penurunan harga yang ada Bablemark2?
TC Proctor
55

Jika Anda menggunakan Jekyll atau octopress berikut juga akan berfungsi.

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

Tag Liquid {% comment %}diuraikan terlebih dahulu dan dihapus sebelum prosesor MarkDown bahkan sampai ke sana. Pengunjung tidak akan melihat ketika mereka mencoba untuk melihat sumber dari browser mereka.

uiroshan
sumber
2
Jinja2 = {#komentar multiline di sini#}
John Mee
29

Alternatifnya adalah dengan memberikan komentar di dalam tag HTML bergaya. Dengan cara ini, Anda dapat mengubah visibilitas mereka sesuai kebutuhan. Misalnya, tentukan kelas komentar di stylesheet CSS Anda.

.comment { display: none; }

Kemudian, MARKDOWN yang disempurnakan berikut

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

muncul sebagai berikut dalam BROWSER

We do support comments

Stu
sumber
5
Salin / tempel kemungkinan akan berakhir menyalin teks "berkomentar" serta teks biasa jadi hati-hati saat menggunakan ini. Itu bisa dengan mudah menghasilkan hasil yang tidak terduga untuk seseorang menyalin blok teks.
Eilon
4
@Eilon juga aksesibilitasnya sangat buruk
Ethan
Mesin pendukung aksesibilitas akan dengan benar melewati tampilan: tidak ada teks.
aredridel
28

Ini bekerja pada GitHub:

[](Comment text goes here)

HTML yang dihasilkan terlihat seperti:

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

Yang pada dasarnya adalah tautan kosong. Jelas Anda dapat membacanya di sumber teks yang diberikan, tetapi Anda tetap dapat melakukannya di GitHub.

jomo
sumber
6
Memang benar, tetapi sebenarnya satu-satunya jawaban sejauh ini yang selalu berfungsi di GitHub, misalnya dalam daftar.
jomo
Saya tiba di solusi yang sama. Ini satu-satunya yang bisa saya kerjakan untuk komentar in-line, mis some text [](hidden text) blah blah.
c24w
3
Ini tidak lagi bekerja di github pada 2019/03/08, itu membuat seperti[](Comment text goes here)
dogmatic69
19

Pengguna Vim Instant-Markdown perlu digunakan

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

Juga lihat Critic Markup, didukung oleh semakin banyak alat 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
sumber
5
Saya pikir salah satu masalah dengan standar "semu" adalah bahwa mereka tidak portabel. Pada beberapa situs web, ini akan bekerja dengan sempurna, pada yang lain, mereka tidak akan berhasil.
Willem Van Onsem
14

Bagaimana dengan menempatkan komentar di blok R non-eval, non-echo? yaitu,

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

Tampaknya bekerja dengan baik untuk saya.

David Kaufman
sumber
2
Juga, jangan ragu untuk melakukan hal-hal seperti di cat("# Some Header")dalam blok kode "berkomentar" dan menggunakan results = "asis", dan Anda dapat menambahkan seluruh bagian komentar keluar ke kode Anda yang dapat dibalik / mati dengan beralih eval = FALSE, karena evaluasi R dilakukan sebelum kompilasi pandoc. Terima kasih atas idenya!
MichaelChirico
11

Pengungkapan: Saya menulis plugin.

Karena pertanyaan tidak menentukan implementasi penurunan harga tertentu, saya ingin menyebutkan Plugin Komentar untuk python-markdown , yang mengimplementasikan gaya komentar pandoc yang sama yang disebutkan di atas.

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

Tidak berfungsi di Pandoc Markdown (Pandoc 1.12.2.1). Komentar masih muncul di html. Berikut ini berhasil:

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

Kemudian gunakan ekstensi + catatan kaki. Ini pada dasarnya adalah catatan kaki yang tidak pernah direferensikan.

Brad Porter
sumber
Saya suka yang terbaik ini, karena tidak menghasilkan output sama sekali. Untuk Bitbucket awalan ini sudah cukup: [#]: .
ceving
7

Berikut ini bekerja dengan sangat baik

<empty line>
[whatever comment text]::

metode yang memanfaatkan sintaks untuk membuat tautan melalui referensi
karena referensi tautan yang dibuat dengan [1]: http://example.orgtidak akan di-render, demikian juga salah satu dari berikut ini tidak akan dirender juga

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever
anapsix
sumber
Varian pertama yang diuji ini berfungsi pandocbaik untuk instance online Gitlab dan GitHub saat ini .
doak
5

Untuk pandoc, cara yang baik untuk memblokir komentar adalah dengan menggunakan metablock yaml, seperti yang disarankan oleh penulis pandoc . Saya telah memperhatikan bahwa ini memberikan sintaks yang lebih tepat dari komentar dibandingkan dengan banyak solusi yang diusulkan lain, setidaknya di lingkungan saya ( vim, vim-pandoc, dan vim-pandoc-syntax).

Saya menggunakan komentar blok yaml dalam kombinasi dengan komentar html-inline komentar html tidak dapat disarangkan . Sayangnya, tidak ada cara untuk memblokir komentar di dalam metablock yaml , sehingga setiap baris harus dikomentari secara terpisah. Untungnya, seharusnya hanya ada satu baris dalam paragraf yang dibungkus dengan lembut.

Di saya ~/.vimrc , saya telah menyiapkan pintasan khusus untuk komentar blokir:

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

Saya menggunakan ,sebagai <Leader>-Kunci saya , jadi ,bdan ,vmengomentari dan menghapus komentar paragraf, masing-masing. Jika saya perlu mengomentari banyak paragraf, saya memetakan j,bke makro (biasanya Q) dan menjalankan <number-of-paragraphs><name-of-macro>(mis. ( 3Q). Hal yang sama berfungsi untuk tidak komentar.

joelostblom
sumber
5

kramdown — mesin penurunan harga berbasis Ruby yang merupakan default untuk Jekyll dan karenanya GitHub Pages — memiliki dukungan komentar bawaan melalui sintaksis ekstensi :

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

Ini memiliki manfaat memungkinkan komentar in-line, tetapi downside tidak portabel untuk mesin Markdown lainnya.

vossad01
sumber
4

Anda dapat mencoba

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

Anda dapat melakukan ini (blok YAML):

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

Saya mencoba dengan keluaran lateks saja, mohon konfirmasi untuk orang lain.

Flo
sumber
Ia bekerja dengan output HTML juga.
petzi
Saya tidak yakin apakah konfirmasi Daniel tentang output html sudah benar. Saya melakukannya dengan file output html dan menjalankan "pandoc --bibliography paper.bib -o paper.html paper.md" dan HTML menunjukkan baris komentar.
markgalassi