Пару лет назад я презентовал на Хабре первую концепцию полнофункциональной текстовой разметки Маркван. Которая позволяет создавать достаточно сложные художественные и технические тексты, а заодно и генерировать статические сайты.
За это время накопилось несколько замечаний, которые необходимо было быстренько поправить. Изначально я планировал уделить проекту всего пару недель. Но, как это часто бывает в разработке, незаметно испарились три месяца. Много времени ушло на перепродумывание самой спецификации и на реализацию нового конвертера. Зато теперь Маркван превратился в строгую, логичную и предсказуемую экосистему.
Изменения в спецификации
Какие-то разделы остались неизменны, а какие-то сильно преобразились.
Например, заголовки остались те же, только добавилась возможность их строчного применения для особых случаем, например, при документировании в коде.
Выделения слов в тексте пришлось изменить, чтобы добиться единства концепции:
~~Курсив~~ **Полужирный** ~_Мелкий_~ ~^Крупный^~ ^^Надстрочный^^ __Подстрочный__ Преформатированный ~-Иностранное слово-~ *-Термин-* -*Упоминание термина*- !-Удалено-! !+Добавлено+!
Списки остались те же, чуть упростились. Комментарии совсем без изменений.
Пришлось ввести такое понятие как Контекстная пара (Context Pair)
Контекстная пара — это монолитная совокупность двух контекстно связанных элементов текста: двух последовательных абзацев, абзаца и последующего за ним списка, либо абзаца и блочного включения. Первый элемент контекстной пары является предикатом, который предсказывает, заявляет и раскрывает содержание второй, зависимой части.
К сноскам звёздочками и цифрами добавились автонумерующиеся сноски [*#].
Ссылки тоже немного расширились:
|>> — ссылка для перехода на внешний ресурс, |> — ссылка для перехода на страницы проекта (или указание исходника изображения), |-> — ссылка для скачивания файла с нашего проекта.
Введение |> #intro
Включений стало больше:
[( … )] — универсальный текстовый блок с поддержкой вложенности; [/ … /] — комментарии; [` … `] — преформатированный текст; [& … &] — программный код; [% … %] — формулы; [| … |] — таблицы; [[ … ]] — медиа (изображения, видео, аудио, файлы для скачивания). [. … .] — группирующее включение (альтернатива таблицам); [_ … _] — включение скрытия (спойлер); [$ … $] — включение ввода данных (интерактивное включение).
Появилась отдельная возможность автоматического агрегирования сущностей, чтобы получить: оглавление, глоссарий или другие сборники.
{§toc Оглавление §}
Появились механизмы встраивания:
1. Импорт нод (модульное слияние файлов, крупных разделов или блоков контента):
{{ |> link#id }}
2. Вставка значений ключей из метаданных в строку, например, для заполнения шаблона договора:
{{key}}
Появилась инъекция кода.
{& Код &}
Подсветка кода
Благодаря Джемини удалось сделать подсветку кода для VSCode. Полагаю, теперь несложно будет написать код подсветки и для других редакторов.
Помимо общей наглядности текста, в этой подсветке есть несколько полезностей. Например, при указании ссылки система проверяет есть ли такой файл и подчёркивает адрес. Прямо в редакторе можно кликать по путям и переходить по ссылкам, прыгать по якорям #id, а при наведении на изображения видеть превью.
Для установки подсветки маркван-кода достаточно поместить папку с кодом в ...vscode\extensions.
Маркван конвертер
Конвертер пришлось переписать с нуля. Теперь он работает примерно так:
Есть файл конфигурации в котором указано откуда взять, что сделать и куда положить. (В будущем можно прикрутить и графический интерфейс). Основная функция просто отправляет на сборку книги либо на создание сайта.
Скоростью и экономией памяти в этот раз решено было пренебречь, как это не прискорбно. Поэтому все текстовые файлы сохраняются в виртуальное дерево, а на прочие оставляем ссылки.
Последовательно обрабатываем каждый .text файл. Разделяем метаданные и сам текст, докачиваем информацию из внешних файлов при наличии команд импорта или встройке данных.
-
Ядро конвертера изолировано от всей этой глобальной суеты и работает только с текстом. Его задача преобразовать маркван-разметку в дерево абстрактных объектов:
Иерархия классов:
Document: — Документ - Metadata — Метаданные - Title — Титульный блок - Section: — Раздел - Node: — Нода - Heading(Node): — Структурирующий аголовок - Paragraph(Node): — Абзац - InlineElement: - и т.д. … - ListBlock(Node): — Блок списка - ListItem(Node): — Элемент списка - ContextPair(Node): — Контекстная пара - Attachment(Node): — Сноски и ссылки - Inclusion(Node): — Включение и т.д. … После парсинга по дереву проходит агрегатор документа и, например, превращает относительные ссылки в корневые, перенумеровывает списки, сноски и прочее подобное. Заодно считаем сколько и каких включений у нас есть — это для оптимизации стилей.
Результат конвертации не спешим сохранять на диск. У нас появилось результирующее дерево страниц из абстрактных нод. Затем нужно пройтись агрегатору уровня сайта и собрать данные, например, для меню.
Теперь можем преобразовывать полученное в html или другой формат. Потом накатываем тему и сохраняем в будущий сайт файлы изображений и других документов, причём только тех, что были упомянуты в тексте, чтобы не отдавать мусор, который может накопиться во время творческих метаний автора. Важное примечание: при генерации веб-страниц в шаблон записываем стили только тех объектов, которые присутствуют в нём. Например, если нет на странице формул, то и незачем грузить яваскрипт их обрабатывающий.
Результат можно посмотреть на самом сайте https://markvan.mudrium.ru/. Он создан из простых текстовых файлов, положенных в папки. Есть и другие сайта, но о них я расскажу позже.
Что дальше?
Скоро сказка сказалась, но на деле не сразу всё придумалось. Это был реальный труд, хоть и интересный. Уделю внимание другим проектам.
Полная обновленная спецификация со всеми примерами, скриншотами и исходным кодом живет на официальном сайте проекта: markvan.mudrium.ru.
Код конвертера ещё сыроват, но я волевым решением приостановил разработку, отложив рефакторинг, чтобы дать проекту отлежаться. Исходники конвертера и расширение VS Code также опубликованы на GitHub.
Проект открыт для обратной связи. Буду рад вашим мыслям по поводу спецификации маркван-разметки. Пишите на почту, в телеграм или прямо здесь в комментариях. В идеале нужно несколько экспериментаторов, у которых есть реальные задачи превратить простой текст в сайт.
Комментарии (27)
rsashka
11.07.2026 12:01Ваш проект (точнее его синтаксис) концептуально напоминает синтаксис NewLang - язык программирования без ключевых слов, только за счет правил синтаксиса. Эта фишка (по задумке) позволяет делать любые DSL, т.к. полностью исключается потенциальная возможность пересечения по ключевым словам.
Но у подобного синтаксиса есть и обратная сторона. Подобный синтаксис сразу перестает быть человекочитаемым. Главное преимущество Markdown, (на основании которого вы начали делать совой проект), заключается в естественном повторении базовых концепций письма (подчекр, выделени и т.д.) и сильной ограниченности в оформительских возможностей.
Расширение оформительских возможностей очень сильно усложняет его понимание и нарушает баланс между удобством и возможностями. Расширений Markdown очень много, но мало какие из них взлетели как раз по этой причине. А ведь XML и HTML и даже CSS тоже являются “текстовыми разметками”, но читать их глазами очень сложно, тогда как Markdown добавляет очень мало “контекстного шума”, и практически не мешает пониманию смысла текста.
OlegZH
11.07.2026 12:01Так в том-то и проблема, что трудно совместить удобство восприятия и удобство редактирования. Как, например, быть с таблицей?
rsashka
11.07.2026 12:01Я не знаю как быть с таблицей, но могу сказать, как быть с DSL на основе синтаксических правил. Нужно делать два синтаксиса - первый (базовый) без ключевых слов, т.е. как и задумывалось, и сразу второй - классический, который из keyword-based преобразуется в первый.
Возможно так и тут. Она часть синтаксиса - простая и естественная, т.е. практический чистый markdown, а вторая часть - специфическая, (а возможно даже несколько отдельных частей). Одна для создания связей, ссылок, вставки картинок, сносок и оглавлений, вторая для оформления таблиц, третья для многоэтажных формул и т.д.
slonopotamus
11.07.2026 12:01Посмотрите как сделаны таблицы в AsciiDoc.
al-chemist
11.07.2026 12:01Для ленивых: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#tables
Для очень ленивых: таблицы в AsciiDoc сделаны омерзительно, автор просто не знает, что такое таблица, и зачем данные в таблицу организуют. Маркдаун прекрасен тем, что если некому его отрендерить, он прекрасно читается в оригинале. Грубер преследовал именно эту цель.
slonopotamus
11.07.2026 12:01Маркдауновые таблицы - ад для редактирования. Ну и в них же ничего нельзя, даже переноса длинных предложений.
al-chemist
11.07.2026 12:01Шуруповертом неудобно заколачивать гвозди? — Сочувствую.
Если вам так нужно насрать на читателя вашего маркдауна, или если вы используете текстовый формат для легкого форматирования — в качестве текстового процессора — к вашим услугам embedded html.
<table>всё еще работает.slonopotamus
11.07.2026 12:01<table> всё еще работает.
Не работает если я хочу сконвертировать док в отличный от HTML формат.
TokSeven
11.07.2026 12:01заключается в естественном повторении базовых концепций письма
В md нет такой базовой вещи, как underline, из-за чего я его не использую
Главное преимущество Markdown заключается в [...] сильной ограниченности в оформительских возможностей
Хочется пошутить про 'только выиграли' и 'только ситхи всё возводят в абсолют', но не буду.
rsashka
11.07.2026 12:01В md нет такой базовой вещи, как underline, из-за чего я его не использую
Ага, самый большой косяк синтаксиса Markdown, это использовать подчерки как выделение жирным, тогда как по логике это просто обязан быть underline. :-(
TokSeven
11.07.2026 12:01А где underline? Вижу что-то похожее в 'добавлено', но там какие-то 2 линии, а в классическом андерлайне - одна
NeoCode2
11.07.2026 12:01Я в своем редакторе заметок активно пользуюсь цветовыми выделениями (то что в html называется "mark", а также выделения целых абзацев, строк и столбцов таблиц и т.д.). Причем не одним цветом, а сразу несколькими (конечно не rgb, но "основные смысловые цвета"). Считаю что это достаточно важная возможность для тех кто интенсивно работает с документами.
IvanKlut Автор
11.07.2026 12:01Размышлял об этом. Но решил, что в готовом документе это не нужно. Возможно такая возможность необходима в режиме творческого размышления. Можете подробнее здесь или в лику расписать для чего именно вы этим пользуетесь, какие смыслы назначаете разным цветам?
AVX
11.07.2026 12:01Я цвета для текста использую для того, чтобы быстро визуально можно было увидеть что-то негативное (красным) или крайне важное и/или опасное, и зеленым наоборот - позитивное, или что-то готовое, решенное (в списке это удобнее галочками, а в середине текста кажется удобнее цветом).
В каких-то случаях сначала делаю примечание, что какой цвет обозначает, и далее так и использую. Например, классификацию чего-то по категориям в таблице с использованием цвета текста позволяет убрать один столбец (где можно категорию указать). Конечно, это только когда категорий не более нескольких штук, иначе можно перепутать цвета, да и в голове сложно удержать соответствие цвет-категория, если их много.
alex-khv
11.07.2026 12:01Текст идёт слева направо. Это одно измерение. Когда мы делаем таблицу от у нас появляется два измерения. Но ещё мы видим цвета. Поэтому таблица с цветами позволяет уже отображать три измерения спроецированные на двухмерную плоскость
VKAT0N
11.07.2026 12:01Не вижу смысла в 100500 вариации md. И синтаксис (?) не понравился. Автору надо, ну и хорошо. Не интересно
kedzoo
11.07.2026 12:01Функционал md ограничен специально. Да и в 99% случаев этого достаточно. Был бы он сложным - сложнее стала бы и его поддержка и использование. А так он уже стал самым распространенным форматом текстов на шарике. Именно из за жестких ограничений.
IvanKlut Автор
11.07.2026 12:01Да, я это понимаю. Просто у меня совершенно иная задача, нежели ставилась перед markdown. И поэтому markvan проще никак не получается.
Dmitrii_Zz
11.07.2026 12:01Статья достаточно интересная. Я ознакомился с информацией на вашем сайте по ссылке из статьи и возникли такие вопросы.
Из целеполагающей идеи и преимуществ Маркван не ясно, чем же она лучше того же Markdown, можно конкретный пример? В md можно точно также оформлять статьи, книги, как преподавателям, так и ученым и не зависеть от бинарников. Если в md вам не хватало каких-то фичей, то не рассматривали ли возможность создания плагина для него, тот же парсер для преобразования файлов md в статическую web страницу?
Еще пока не успел полностью ознакомиться, но заинтересовался самой возможностью создания статических web сайтов из простых текстовых сайтов. Там же нет js, только html? И как подбирается дизайн. Он один или конечный html можно редактировать? Я согласен с тем, что современные сайты перегружены презентационными блоками на весь экран, но однотипные статические web страницы не подавляют идентичность и уникальность сайтов?
IvanKlut Автор
11.07.2026 12:01Дело в том, что при создании Марквана я абстрагировался от веб-отрасли. Была задача создать абстрактное представление не виртуального, а практического книгоиздания (естественно со всеми выгодами гиперссылок и кода). Есть мысли определенным образом переструктурировать информацию, выделив всё что есть полезного у человечества, отсеив некачественное и мусор. Но боюсь, задача усложняется с каждым днём :-)
Что касается технологий. Статический веб-сайт может быть весьма функционален. Посмотрите здесь https://markvan.mudrium.ru/osnovnaya_spetsifikatsiya/vklyucheniya/tehnicheskie.html есть включения с формулами, диаграмами, нотами, картами. Это всё яваскрипт. Я ещё во второй версии не успел сделать демку (в первой была) -- там был онлайн-редактор, где вы могли побаловаться вводом марквана и одновременным его преобразованием в ХТМЛ.
Кроме того, не так уж и сложно реализовать даже поиск по сайту.
Если добавлять в статический сайт электронную коммерцию, то с этим сложнее. Пока не размышлял. Придётся вероятно встраивать виджеты от банков. Есть, конечно и сервисы встраивающие процессинг магазина в сайт, когда-то был Эквид, сейчас не знаю.
Ну а стили вы можете вообще какие заблагорассудится вставлять.
Т.е. есть папка с вашим контентом, а есть папка с темой и конвертер всё это объединяет в готовый сайт.
js2me
11.07.2026 12:01Красиво и практично!
Успехов вам в продвиженииIvanKlut Автор
11.07.2026 12:01Спасибо. Особо продвигать не планирую, это пока инструмент для решения своих задач, ну и проверка себя на креативность. Сейчас работаю над более фундаментальным проектом. Как закончу, может и вернусь к этому.
SantyagoNN
11.07.2026 12:01Скрытый текст
По моему вы ушли от простоты markdown. Запомнить всё это тяжело, легче html выучить. Или использовать https://github.com/ntrupin/abstractml если теги html лениво набивать.
IvanKlut Автор
11.07.2026 12:01Пришлось чуть усложнить. Необходимо было заложить гораздо больше смыслов чем в маркдовн и в хтмл. Да и веб в этом проекте вторичен, задачи у стандарта иные (но об этом не в ближайшее время).
На самом деле маркван запоминается легко, если понять общие принципы и у пользователя есть реальная задача.
kpbsod
11.07.2026 12:01Выглядит круто, желаю автору развить проект. Самый главный недостаток — это отсутствие поддержки основных IDE. Я бы воспользовался инструментом только при наличии плагина в Jetbrains IDEA. Необходима подсветка синтаксиса, отрисовка результата на лету, автодополнение кода.
Как по мне — это главная проблема многих подобных проектов. Почему-то разработчики никогда не задумывался о том, как другие пользователи этих проектов будут пользоваться этими инструментами.
IvanKlut Автор
11.07.2026 12:01Спасибо большое. Про пользователей задумывался, но на всё времени не хватает.
Джетбрейнс раньше пользовался, но потом они ограничили регион пользования. С подсветкой кода не должно быть сложно. Если вдруг вам захочется её сделать, то можете взять все регулярки из подсветки для ВСКода и скормить нейросетке. Даже бесплатная Джемини должна справиться. У меня не скоро руки до этого дойдут. А отрисовка на лету это вы имеете в виду чтобы мгновенно всё переводилось в html и можно было наблюдать результат в браузере? Что-то я даже не подумал что это возможно, а похоже идея рабочая.
OlegZH
Любопытно.