7

Нужно добавить в документ на Markdown комментарии, которые бы не экспортировались в итоговый документ.

Есть стандартный html-комментарий:

<!-- comment text --> 

Проблема в том, что при экспорте такой комментарий попадает в итоговый документ в неизменном виде. Можно ли сделать такие комментарии, которые будут вырезаться при экспорте в HTML?

2
  • 1
    А зачем это надо?
    – Qwertiy
    Commented 16 дек. 2015 в 8:26
  • @Qwertiy: например, я пишу документацию. Исходники в Markdown, результат собирается в PDF или HTML. Я не хочу, чтобы конечные пользователи видели мои комментарии.
    – Nick Volynkin
    Commented 16 дек. 2015 в 8:30

1 ответ 1

10

Это реализуемо с помощью ярлыка ссылки (link label), с которым не связывается ни одна ссылка. Эти ярлыки ссылок будут вырезаны при экспорте:

(пустая строка)
[comment]: # (comment text)

(пустая строка)
[//]: # (comment text)

Сравните с обычным синтаксисом ссылки:

[link text][label]

[label]: http://ru.stackoverflow.com/questions/ask

В принципе, спецификация Markdown допускает вариант, когда перед комментарием нет пустой строки, а вместо # используется <>. Проблема в том, что спецификация дырява как решето, а имеющиеся 28+ реализаций работают по–разному. Добро пожаловать в Markdown!

Проверить работу различных реализаций нам поможет инструментарий Babelmark2, проверяющий рендеринг разметки Markdown в различных реализациях. (+ — прошли тест, - — не прошли, ? — оставляют неотображаемый мусор в HTML).

Согласно проверке, наиболее платформо-независимый вариант — это # и пустая строка перед комментарием. Пустая строка после комментария не играет роли. В частности, набирающая популярность строгая спецификация CommonMark, в разработке которой участвует Jeff Atwood, работает именно с этим вариантом (и не работает с <> и/или без пустой строки)

C этими реализациями нет никакой возможности использовать такие комментарии:

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

Исследование основано на решении, предложенном участником Magnus на SO.EN.

Ваш ответ

Нажимая «Отправить ответ», вы соглашаетесь с условиями пользования и подтверждаете, что прочитали политику конфиденциальности.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.