LibreTimes Markdown и CommonMark

LibreTimes Markdown — это CommonMark с расширениями GitHub плюс небольшой набор дополнений для математических и научных текстов. Если вы писали Markdown на GitHub, в блокноте или в генераторе статических сайтов, почти всё, что вы знаете, остаётся в силе. Эта страница говорит, что переносится без изменений, что добавлено, в каких немногих местах диалект ведёт себя иначе и чего он намеренно не делает.

То же, что в CommonMark и GitHub

Абзацы, заголовки, выделение, списки, ссылки, изображения, цитаты, код в строке и блоки кода в ограждениях работают в точности по CommonMark. Из GitHub Flavored Markdown диалект берёт таблицы, списки задач, сноски, автоссылки и ~~зачёркивание~~.

Поэтому обычный документ CommonMark уже является корректным документом LibreTimes и отображается так, как вы ожидаете. Этот слой описан на страницах основ — в основном ради пограничных случаев.

Что добавлено

Каждое дополнение отвечает на потребность, которую обычный Markdown оставляет сырому HTML или картинке с результатом.

• Математика, записанная на LaTeX между знаками доллара: $x^2$ в строке и $$ на отдельных строках для выключной формулы. Это единственное место, где синтаксисом служит LaTeX: лучшей записи формул нет, и каждый математик уже на нём пишет. См. Пишите математику.
• Директивы — блоки :::name … :::. Теорема, доказательство, предупреждение, рисунок с подписью, сворачиваемое решение, группа вкладок и диаграмма TikZ — всё это директивы, так что один синтаксис покрывает каждый блок, который добавляет диалект. В справочнике синтаксиса перечислены все имена.
• Разметка в строке: ==выделение==, нижние ~sub~ и верхние ^super^ индексы и списки определений.
• Атрибуты блоков — строка вроде {align=center} или {#key-table} прямо над блоком, для немногих свойств, которые бывают у блока: как стоят его строки, какой отступ у первой строки и якорь, на который могут ссылаться другие.
• Люди и файлы: @handle ссылается на профиль человека, а :attach[…] — на файл, прикреплённый к работе.
• Видео, @[youtube](…) и @[vimeo](…) — единственные два встраиваемых плеера.

Что изменено

Четыре правила отличаются от того, что сделал бы с тем же текстом другой Markdown. У каждого есть причина, и каждое — место, где документ, написанный в другом месте, может вас удивить.

Одиночная тильда — нижний индекс

H~2~O — нижний индекс, а для зачёркивания нужны две тильды с каждой стороны, ~~вот так~~. GitHub принимает для зачёркивания и одиночную тильду; здесь эта форма проглотила бы каждую химическую формулу, поэтому она отключена. GitHub тоже понимает форму с двумя тильдами, так что документ, написанный для обоих, читается одинаково.

Два дефиса — это тире

-- становится коротким тире, а --- — длинным, в документах и в заголовках. Кавычки и многоточия остаются ровно такими, как набраны: правильные кавычки зависят от языка, а неверная догадка хуже прямых кавычек. Чтобы дефисы остались дефисами, поместите их в код в строке: `--verbose`.

Заголовок работы — верхний заголовок

Заголовок, который вы даёте работе, — единственный заголовок верхнего уровня на странице, поэтому разделы текста начинаются с ## и идут до ####. Документ, в котором # всё же есть, например написанный в другом месте, не сплющивается: каждый его заголовок опускается на один уровень, так что разделы сохраняют порядок и вложенность. Уровни глубже четвёртого сливаются в четвёртый.

Причина — оглавление. Страница с двумя заголовками верхнего уровня даёт экранному диктору два документа, поисковику — два названия, а оглавлению рядом с текстом — дерево с двумя корнями. Сдвиг всех заголовков сохраняет то, что вы написали, и оставляет у страницы одно название.

Сырой HTML фильтруется

HTML в исходном тексте допустим и проходит через фильтр, который оставляет короткий список безвредных элементов и удаляет всё остальное: скрипты, стили, формы и фреймы, кроме видеоплееров. См. HTML и безопасность.

От чего диалект отказывается

Правило, стоящее за дополнениями: разметка говорит, что такое вещь, и никогда — как она выглядит. Теорема помечается как теорема, а её полужирная метка и курсив следуют из этого — на странице, в PDF и у экранного диктора одинаково. То же правило раз и навсегда исключает некоторые вещи, чтобы их не обсуждать заново по каждому запросу:

• Шрифты, размеры, цвета и интервалы. Они принадлежат странице, которая показывает текст, а не тексту. Место, которое должно выделяться, — это выделение, выноска или утверждение, и каждое из них говорит, почему оно выделено.
• Длины. Блок можно выровнять по центру или дать ему висячий отступ — это именованные значения, которые каждый вывод исполняет в своей мере. Ширину или поле в сантиметрах задать нельзя.
• Колонки, плавающие блоки и разрывы страниц. Вёрстка страницы — дело экспорта, а не исходника, общего для всех выводов.
• LaTeX вне математики. \begin{theorem}, \section и \emph в тексте не читаются. Файл .tex попадает на платформу через импорт, который один раз переписывает их на диалект, вместо того чтобы страница каждого читателя вечно разбирала LaTeX.
• Переносы строк, скопированные с печатной страницы. Проза перетекает под экран читателя. Стихи сохраняют свои строки в блоке стихов.

Опечатка остаётся видна

Словарь диалекта закрыт: есть фиксированный набор имён директив и ключей атрибутов. Всё, что вне его, отображается теми символами, которые вы набрали. У опечатки :::theorm на странице видны строки ограждения, а тело между ними по-прежнему отображается как Markdown, и {alig=center} печатается, а не пропускается.

Это сделано намеренно. Рендерер, который угадывал бы, превратил бы опечатку в тихое изменение смысла, а рендерер, отбрасывающий незнакомое, спрятал бы её. Честный результат — то, что вы написали, там, где его увидит корректор.

Короткие поля принимают меньше

Заголовки, аннотации, биографии и записи в резюме тоже пишутся в Markdown, но не во всём диалекте: они показываются там, где блоку не место, — во вкладке браузера, в результате поиска, в экспорте ссылки.

Всё прочее в этих полях показывается простым текстом. $$ там не математика: выключная формула в заголовке никогда не бывает тем, что имелось в виду. Комментарии принимают форматирование текста и математику, но не медиа и не блоки; см. Комментарии.

Один синтаксис для хранимого текста

У некоторых конструкций есть второе написание, которое LibreTimes читает только при импорте. Главное из них — алерт GitHub > [!NOTE]: набранный в документе, он остаётся обычной цитатой, а в файле, который вы импортируете, становится :::note. Одно написание для хранимого текста означает, что любой документ можно редактировать, искать и конвертировать по одним и тем же правилам и два автора никогда не спорят, какая форма актуальна.