Коментарі в Markdown

Що таке синтаксис для зберігання коментаря у файлі розмітки, наприклад, коментар CVS $ Id $ у верхній частині файлу? Я нічого не знайшов у проекті розмітки .

Я вважаю, що всі запропоновані раніше рішення (крім тих, що потребують конкретних реалізацій) призводять до того, що коментарі включаються до вихідного HTML, навіть якщо вони не відображаються.

Якщо ви хочете, щоб коментар був суто для вас самих (читачі перетвореного документа не зможуть його бачити, навіть із "джерелом перегляду"), ви можете (ab) використовувати мітки посилань (для використання із посиланнями стильового стилю), які є доступний в основній специфікації Markdown:

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

Це є:

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

Або ви могли піти далі:

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

Для покращення сумісності платформи (та збереження одного натискання клавіш) також можна використовувати #(що є законною ціллю гіперпосилання) замість <>:

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

Для максимальної переносимості важливо вставити порожній рядок до та після коментарів, оскільки деякі парсерви Markdown не працюють належним чином, коли визначення визначаються з звичайним текстом. Найсвіжіші дослідження Babelmark показують, що порожні рядки до і після є обома важливими. Деякі парсери виведуть коментар, якщо раніше немає порожнього рядка, а деякі парсери виключають наступний рядок, якщо після цього немає порожнього рядка.

Взагалі цей підхід повинен працювати з більшістю парсерів Markdown, оскільки він є частиною основної специфікації. (навіть якщо поведінка, коли визначено кілька посилань або коли посилання визначено, але ніколи не використовується, не є чітко визначеною).

Я використовую стандартні теги HTML, наприклад

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

Зверніть увагу на потрійний тире. Перевага полягає в тому, що він працює з pandoc при генерації виводу TeX або HTML. Додаткову інформацію можна отримати в групі, присвяченій обговоренню .

Це невелике дослідження підтверджує та уточнює відповідь Магнуса

Найбільш незалежний від платформи синтаксис

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

Обидві умови важливі:

1. Використання #(а не <>)
2. З порожнім рядком перед коментарем . Порожній рядок після коментаря не впливає на результат.

Сувора специфікація Markdown CommonMark працює лише за призначенням із цим синтаксисом (а не із <>та / або порожнім рядком)

Для доведення цього ми використаємо Babelmark2, написаний Джоном Макфарланом. Цей інструмент перевіряє візуалізацію конкретного вихідного коду в 28 реалізаціях Markdown.

( +- пройшов тест, -- не пройшов, ?- залишає сміття, яке не відображається у виведеному HTML).

• Немає порожніх рядків, використовуючи<> 13+, 15-
• Порожній рядок перед коментарем, використовуючи<> 20+, 8-
• Порожні рядки навколо коментаря, використовуючи<> 20+, 8-
• Немає порожніх рядків, використовуючи# 13+ 1? 14-
• Порожній рядок перед коментарем, використовуючи # 23+ 1? 4-
• Порожні рядки навколо коментаря, використовуючи# 23+ 1? 4-
• HTML коментар з 3 дефісами 1+ 2? 25- з відповіді chl (зауважте, що це різний синтаксис)

Це доводить твердження вище.

У цих реалізаціях проходять усі 7 тестів. Немає шансів використовувати коментарі, що виключаються на рендерінг, з ними.

• cebe / розмітка 1.1.0
• cebe / markdown MarkdownExtra 1.1.0
• cebe / розмітка GFM 1.1.0
• s9e \ TextFormatter (Fatdown / PHP)

Якщо ви користуєтесь Jekyll або octopress, наступне також буде працювати.

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

Рідкі теги {% comment %}розбираються спочатку та видаляються ще до того, як процесор MarkDown навіть потрапить на нього. Відвідувачі не побачать, коли вони намагаються переглянути джерело зі свого браузера.

Альтернативою є розміщення коментарів у стилізованих тегах HTML. Таким чином, ви можете перемикати їх видимість у міру необхідності. Наприклад, визначте клас коментаря у вашій таблиці стилів CSS.

.comment { display: none; }

Потім, наступний розширений MARKDOWN

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

відображається наступним чином у BROWSER

We do support comments

Це працює на GitHub:

[](Comment text goes here)

Отриманий HTML виглядає так:

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

Що в основному порожнє посилання. Очевидно, що ви можете прочитати це у джерелі викладеного тексту, але це все одно можна зробити на GitHub.

Користувачам Vim Instant-Markdown потрібно користуватися

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

Також дивіться критичну розмітку, підтримувану все більшою кількістю інструментів 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.

Як щодо розміщення коментарів у неевальському, нееховому блоці R? тобто

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

Здається, для мене це добре працює.

Розкриття: я написав плагін.

Оскільки питання не визначає конкретної реалізації розмітки, я хотів би згадати Плагін Comments for python-markdown , який реалізує той самий стиль коментування pandoc, який згаданий вище.

<!--- ... --> 

Не працює в Pandoc Markdown (Pandoc 1.12.2.1). Коментарі все ще з'явилися в html. Робили наступне:

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

Потім скористайтеся розширенням виноски +. Це, по суті, виноска, на яку ніколи не посилаються.

Наступне працює дуже добре

<empty line>
[whatever comment text]::

цей метод використовує перевагу синтаксису для створення посилань за допомогою посилань,
оскільки посилання на посилання, створене за допомогою [1]: http://example.org, не буде надано, також будь-яке з наведених нижче даних також не буде надано

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

Для pandoc хороший спосіб блокувати коментар - це використовувати метаблок yaml, як запропонував автор pandoc . Я помітив , що це дає більш правильну підсвічування синтаксису зауважень по порівнянні з багатьма іншими запропонованими рішеннями, по крайней мере , в моєму оточенні ( vim, vim-pandocі vim-pandoc-syntax).

Я використовую коментарі блоку yaml у поєднанні з html-вбудованими коментарями, оскільки html-коментарі не можуть бути вкладеними . На жаль, немає можливості блокувати коментування в метаблоку yaml , тому кожен рядок повинен коментуватися індивідуально. На щастя, у м'якому обзаведеному абзаці має бути лише один рядок.

В моєму випадку ~/.vimrcя створив спеціальні ярлики для блокування коментарів:

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

Я використовую ,як мій <Leader>-Key, так ,bі ,vкоментувати і розкоментувати абзац, відповідно. Якщо мені потрібно коментувати декілька абзаців, я перетворюю j,bна макрос (як правило Q) і запускаю <number-of-paragraphs><name-of-macro>(наприклад ( 3Q). Те саме працює для коментарів).

kramdown - двигун розмітки на основі Ruby, який є за замовчуванням для Jekyll і, таким чином, GitHub Pages - має вбудовану підтримку коментарів через синтаксис розширення :

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

Це має перевагу в тому, що ви можете отримувати вбудовані коментарі, але недоліком не є переносність для інших двигунів Markdown.

Ви можете спробувати

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

Ви можете зробити це (блок YAML):

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

Я намагався тільки з латексним виведенням, будь ласка, підтвердьте інші.