Комментарии в уценке

1402

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

Betamos
источник
10
Читая между строк, кажется, что вы хотите прикрепить метаданные к вашему Markdown. По этой причине я бы предложил использовать препроцессор, который позволит вам добавить заголовок. Для одного примера, см . Фронтальное дело Джекилла . Для другого примера посмотрите, как Basho использует Middleman для своей документации . (Примечание: это не прямой ответ на вопрос, поэтому я делюсь им как комментарием.)
Дэвид Дж.
2
Смотрите также, как MultiMarkdown поддерживает метаданные .
Дэвид Дж.
Вот эталон разных типов комментариев с разными парсерами на Babelmark .
Ulysse BN

Ответы:

1457

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

Магнус
источник
145
[//]: # "Comment"и, [//]: # (Comment)кажется, работают над более широким спектром реализаций, потому что #это допустимый относительный URI. GitHub, например, отклоняет <>, и вся строка становится видимой. Стоит также отметить, что ярлыки ссылок часто необходимо отделять от другого содержимого пустой строкой.
Zenexer
6
Чтобы быть максимально независимым от платформы, ему также нужна пустая строка перед комментарием. Смотрите тесты: stackoverflow.com/a/32190021/2790048
Ник Волынкин
6
Можно ли это использовать для многострочных комментариев?
crypdick
4
@RovingRichard Да, по крайней мере, в Pandoc это работает для многострочных комментариев, если в прокомментированном блоке нет пустых строк (однострочные разрывы хороши). Я использую подход Магнуса для блочных комментариев и подход chl для встроенных комментариев (хотя обычно только 2 черточки). Таким образом, я могу заблокировать комментарии, уже содержащие встроенные комментарии HTML.
Joelostblom
4
Просто к сведению, но если вы создаете оглавление с помощью Pandoc, это сгенерирует предупреждение о дубликатах ссылок. (Это всего лишь предупреждения, оглавление все равно будет создано.)
Карл Гизинг
996

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

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

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

хл
источник
73
Если я правильно понимаю, тройной тире заставляет pandoc игнорировать комментарий при анализе файла уценки. Но если вы используете другой механизм уценки, комментарий будет отображаться в сгенерированном HTML (и, следовательно, будет виден при «просмотре исходного кода»). Таким образом, вы должны быть осторожны, что вы положили в этом комментарии;)
cberzan
5
Можете ли вы объяснить, как Pandoc трактует тройные черты иначе, чем двойные? Когда я экспериментировал с ними, с ними, похоже, поступили так же. Кроме того, в руководстве пользователя Pandoc просто сказано: «Необработанный HTML пропускается без изменений в выходных данных HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown и Textile и подавляется в других форматах». Кажется, что тройные черты не имеют более высоких привилегий, чем двойные.
Декабрь
1
@dkim Комментарии с тройной чертой игнорируются и удаляются из вывода HTML. Это не относится к двойным пунктирным комментариям, которые вставляются в файл HTML. Это все еще относится к последней версии Pandoc (1.10).
ЧЛ
32
Если тройной штрих важен, то это не «стандартные HTML» комментарии.
tripleee
17
Примечание для Google: это, к сожалению, не работает в GitHub Markdown, и я решил использовать решение Magnus.
Даниэль Бакмастер
198

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

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

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

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

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

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

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

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

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

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

  • cebe / уценка 1.1.0
  • cebe / markdown MarkdownExtra 1.1.0
  • cebe / уценка GFM 1.1.0
  • s9e \ TextFormatter (Fatdown / PHP)
Ник волынкин
источник
3
Отличный, тщательный инструмент тестирования! Похоже, вы правы, что # работает для всех, кроме GFM и <> работает для GFM, но не пара других. Жаль, что GFM - это и угловой случай, и очень популярный аромат.
варенье
1
Похоже, s9e \ TextFormatter работает с # 21 января 2016 года. Cebe по-прежнему не справляется с этим.
Трой Дэниелс
1
Странно, если комментарий содержит (...)сам по себе, он нарушает его. По крайней мере, в Visual Studio Code 1.19.
Рой
1
и, следовательно, для пользователей vim, которые хотят прокомментировать все файлы сразу:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.
Что это говорит о уценке, что Bablemark2 существует?
Проктор ТК
55

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

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

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

uiroshan
источник
2
Jinja2 = {#многострочные комментарии здесь#}
Джон Ми
29

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

.comment { display: none; }

Затем следующее усиление MARKDOWN

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

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

We do support comments

Stu
источник
5
Копирование / вставка, скорее всего, приведет к копированию «закомментированного» текста, а также обычного текста, поэтому будьте осторожны при использовании этого. Это может легко привести к неожиданным результатам для кого-то, кто копирует блок текста.
Eilon
4
@Eilon также доступность для этого была бы ужасна
Этан
Механизмы поддержки специальных возможностей будут правильно пропускать отображение: текст отсутствует.
Аредридель
28

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

[](Comment text goes here)

Полученный HTML выглядит так:

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

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

йомо
источник
6
Это определенно так, но пока это единственный ответ, который всегда работает на GitHub, например, в списках.
Джомо
Я пришел к тому же решению. Это единственное, что я могу получить для встроенных комментариев, например some text [](hidden text) blah blah.
c24w
3
Это больше не работает на github с 2019-03-08, оно отображается как[](Comment text goes here)
dogmatic69
19

Пользователи Vim Instant-Markdown должны использовать

<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->
Алекс
источник
18

Также см. Критическая разметка, поддерживаемая растущим числом инструментов разметки.

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.
Керим
источник
5
Я думаю, что одна из проблем с такими "псевдо" стандартами заключается в том, что они не являются переносимыми. На некоторых сайтах они будут работать идеально, на других - нет.
Виллем Ван Онсем
14

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

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

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

Дэвид Кауфман
источник
2
Кроме того, не стесняйтесь делать что-то вроде cat("# Some Header")внутри «закомментированных» блоков кода и использовать их results = "asis", и вы можете добавлять в код целые закомментированные разделы, которые можно включать и выключать переключением eval = FALSE, поскольку оценка R выполняется до Пандок сборник. Спасибо за идею!
MichaelChirico
11

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

Поскольку в вопросе не указана конкретная реализация разметки, я бы хотел упомянуть плагин Comments для 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

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

Брэд Портер
источник
Мне нравится это лучше всего, потому что это не генерирует никакого вывода вообще. Для Bitbucket этот префикс достаточно: [#]: .
Завтра
7

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

<empty line>
[whatever comment text]::

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

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever
anapsix
источник
Это (протестированный первый вариант) работает pandocтак же, как и текущие онлайн-экземпляры Gitlab и GitHub .
Доак
5

Для 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>ключ, так ,bи ,vкомментарий и раскомментируем абзац, соответственно. Если мне нужно прокомментировать несколько абзацев, я сопоставляю j,bих с макросом (обычно Q) и запускаю <number-of-paragraphs><name-of-macro>(например, ( 3Q). То же самое работает для раскомментирования.

joelostblom
источник
5

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.

vossad01
источник
4

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

[](
Your comments go here however you cannot leave
// a blank line so fill blank lines with
//
Something
)
magaga
источник
4

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

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

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

Фло
источник
Он также работает с выводом HTML.
Petzi
Я не уверен, что Даниэль подтвердил вывод html правильно. Я сделал это с помощью выходного файла html и запустил «pandoc --bibliography paper.bib -o paper.html paper.md», и в HTML были показаны строки комментариев.
Markgalassi