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

Каков синтаксис для хранения комментария в файле уценки, например, комментарий 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. Больше информации доступно в группе обсуждения pandoc .

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

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

(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 - из ответа ЧЛ (обратите внимание, что это другой синтаксис)

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

Эти реализации не проходят все 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 %}

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

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

.comment { display: none; }

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

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

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

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

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

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.

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

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

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

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

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

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