Комментарии в Markdown

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

Ответ 1

Я считаю, что все ранее предложенные решения (кроме тех, которые требуют конкретных реализаций) приводят к тому, что комментарии включаются в выходной 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, так как он является частью базовой спецификации. (даже если поведение, когда определено несколько ссылок или когда ссылка определена, но никогда не используется, строго не указано).

Ответ 2

Я использую стандартные HTML-теги, например

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

Обратите внимание на тройную тире. Преимущество заключается в том, что он работает с pandoc при генерации выходных данных TeX или HTML. Дополнительная информация доступна в группе pandoc-discuss.

Ответ 3

Это небольшое исследование доказывает и уточняет ответ Магнуса

Наиболее независимый от платформы синтаксис

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

Оба условия важны:

Используя # (а не <>)
С пустой строкой перед комментарием. Пустая строка после комментария не влияет на результат.

Строгая спецификация Markdown CommonMark работает только с этим синтаксисом (а не с помощью <> и/или пустой строки)

Чтобы доказать это, мы будем использовать Babelmark2, написанный Джоном МакФарлейном. Этот инструмент проверяет рендеринг конкретного исходного кода в 28 реализациях Markdown.

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

Нет пустых строк, используя <> 13+, 15-
Пустая строка перед комментарием, используя <> 20+, 8-
Пустые строки вокруг комментария, используя <> 20+, 8-
Нет пустых строк, используя # 13+ 1? 14-
Пустая строка перед комментарием, используя # 23+ 1? 4-
Пустые строки вокруг комментария, используя # 23+ 1? 4-
Комментарий HTML с тремя дефисами 1+ 2? 25- из ответа chl (обратите внимание, что это другой синтаксис)

Это доказывает вышеприведенные утверждения.

Эти реализации не дают всех 7 тестов. Там нет возможности использовать комментарии с включенными комментариями.

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

Ответ 4

Если вы используете Jekyll или octopress, следующий также будет работать.

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

Жидкостные теги {% comment %} сначала анализируются и удаляются до того, как процессор MarkDown дойдет до него. Посетители не будут видеть, когда они попытаются просмотреть источник из своего браузера.

Ответ 5

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

.comment { display: none; }

Затем следующий расширенный MARKDOWN

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

выглядит следующим образом в BROWSER

We do support comments

Ответ 6

Это работает на GitHub:

[](Comment text goes here)

Результат HTML выглядит так:

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

Это пустая ссылка. Очевидно, вы можете прочитать это в исходном тексте, но вы можете сделать это на GitHub в любом случае.

Ответ 7

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

Ответ 8

Пользователям Vim Instant-Markdown необходимо использовать

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

Ответ 9

Как насчет размещения комментариев в блоке non-eval, non-echo R? то есть.,

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

Кажется, хорошо работает для меня.

Ответ 10

Раскрытие информации: я написал плагин.

Поскольку вопрос не указывает конкретную реализацию уценки, я хотел бы упомянуть плагин комментариев для python-markdown, который реализует тот же стиль комментариев pandoc, упомянутый выше.

Ответ 11

<!--- ... -->

Не работает в Pandoc Markdown (Pandoc 1.12.2.1). Комментарии все еще появились в html. Было выполнено следующее:

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

Затем используйте расширение + footnote. Это, по сути, сноска, на которую никогда не ссылаются.

Ответ 12

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

Я использую комментарии блока yaml в сочетании с комментариями html-inline, поскольку html-комментарии не могут быть вложены. К сожалению, не существует комментариев в блочном комментировании в яблочном блоке обмена, поэтому каждая строка должна быть прокомментирована отдельно. К счастью, в параграфе с мягкой оболочкой должна быть только одна строка.

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

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

Я использую , как my <Leader> -key, поэтому ,b и ,v комментируют и раскомментируют абзац, соответственно. Если мне нужно прокомментировать несколько абзацев, сопоставьте j,b с макросом (обычно Q) и запустите <number-of-paragraphs><name-of-macro> (например, (3Q)). То же самое работает для раскола.

Ответ 13

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.

Ответ 14

Вы можете попробовать

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

Ответ 15

Следующее работает очень хорошо

<empty line>
[whatever comment text]::

этот метод использует синтаксис для создания ссылок по ссылке
поскольку ссылка на ссылку, созданная с помощью [1]: http://example.org, не будет отображаться, также не будет отображаться любое из следующего:

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

Ответ 16

Вы можете сделать это (блок YAML):

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

Я пытался только с выходом латекса, пожалуйста, подтвердите для других.

Ответ 17

Github README.md ИЛИ Stackoverflow отвечает

Для ответов Github README или Stackoverflow я использую # для встроенного комментария.

Пример:


# clone the remote repository to your local machine

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

# change directory

cd echebaby

# install dependencies

yarn install