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

Question

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

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

Answer 2

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

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

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

Answer 3

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

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

(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- * 1 058 *
• Пустые строки вокруг комментария, используя # 23+ 1? 4- * * одна тысяча шестьдесят три
• HTML-комментарий с 3 дефисами 1+ 2? 25 - из ответа chl (обратите внимание, что это другой синтаксис)

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

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

• cebe / markdown 1.1.0
• cebe / markdown MarkdownExtra 1.1.0
• cebe / уценка GFM 1.1.0
• s9e \ TextFormatter (Fatdown / PHP)

Answer 4

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

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

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

Answer 5

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

.comment { display: none; }

Затем в БРАУЗЕРЕ

* 1013 появляется следующая улучшенная ОТКРЫТАЯ

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

следующим образом*

Answer 6

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

[](Comment text goes here)

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

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

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

Answer 7

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

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

Answer 8

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

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.

Answer 9

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

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

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

Answer 10

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

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