Markvan — разметка для книг, документации и статических сайтов из обычного текста

Markvan хранит структуру произведения в простых текстовых файлах и поддерживает элементы, которых часто не хватает компактным языкам разметки: главы, сноски, формулы, таблицы, медиа, учебные задания и импорт фрагментов. Проект уже подходит для экспериментов с книгами, справочниками и статическими сайтами, но конвертер версии 0.8 остаётся бета-инструментом и требует проверки на реальных материалах.

Markvan описывает смысловую структуру документа в читаемом текстовом файле

Markvan, или «Маркван», — открытая система текстовой разметки для художественных произведений, учебных материалов, научных статей и технической документации. Автор пишет содержимое в обычном текстовом редакторе, добавляет служебные символы, а конвертер преобразует исходник в оформленный документ или веб-страницу.

Основная идея знакома пользователям Markdown: текст остаётся читаемым даже без предварительного рендеринга. Различие проявляется в масштабе модели документа. Markvan описывает название произведения, части, главы, разделы, термины, сноски, формулы, таблицы, изображения, программный код и специализированные учебные блоки.

Простейший фрагмент выглядит так:

*** Руководство по домашнему серверу

=== Подготовка системы

Установите **обновления безопасности** перед настройкой служб.

- Проверьте свободное место
- Создайте резервную копию
- Обновите пакеты

Три звёздочки обозначают название произведения, три знака равенства создают заголовок первого уровня, двойные звёздочки выделяют полужирный текст, а дефисы формируют список. Полная спецификация Markvan отделяет логическую структуру от шрифтов, цветов и отступов. Оформление задаётся позже, во время преобразования исходника.

Такой подход удобен для материалов, которые планируют выпускать в нескольких формах. Один комплект исходных файлов можно использовать для веб-версии, электронной книги, печатного макета или внутренней базы знаний. Автор правит содержание в одном месте, а шаблон отвечает за внешний вид каждого формата.

Новая спецификация расширяет ссылки, включения и сборку крупных проектов

Обновлённая версия Markvan была представлена 11 июля 2026 года. В ней автор переработал часть синтаксиса, переписал конвертер и добавил механизмы для многофайловых проектов. Изменения затрагивают как набор текста, так и последующую автоматическую обработку документа.

Система выделений охватывает несколько смысловых ролей:

**Полужирный**
~~Курсив~~
~_Мелкий текст_~
~^Крупный текст^~
^^Надстрочный^^
__Подстрочный__
~-Иностранное слово-~
*-Определяемый термин-*
!-Удалённый фрагмент-!
!+Добавленный фрагмент+!

Markvan использует разные обозначения для внешних адресов, локальных путей и загружаемых файлов:

|>> https://example.com
|> chapters/intro.text
|-> files/manual.pdf

Такое разделение даёт конвертеру больше информации о назначении ссылки. Внешний адрес ведёт на другой ресурс, локальный путь связывает части проекта, а отдельный маркер указывает на скачивание файла.

Для сложного содержимого предусмотрены включения:

[( ... )]   текстовый блок
[& ... &]   программный код
[% ... %]   формула
[| ... |]   таблица
[[ ... ]]   изображение, видео, аудио или файл
[_ ... _]   скрываемый блок
[$ ... $]   поле ввода

Включение может иметь тип, класс, идентификатор и название. Благодаря этому один и тот же смысловой блок получает подходящее оформление в разных шаблонах. Предупреждение можно показать цветной рамкой на сайте, а в печатной версии — значком и отдельным абзацем.

Ещё одно заметное новшество — импорт нод, то есть самостоятельных структурных элементов документа:

{{
|> chapters/network.text#firewall
}}

Команда позволяет подключить раздел или блок из другого файла. Большую книгу можно разбить на главы, документацию — на отдельные модули, а повторяющиеся сведения хранить в одном источнике. Изменение импортируемого фрагмента попадёт во все сборки, где он используется.

Метаданные тоже участвуют в шаблонах. Запись {{key}} подставляет значение ключа в строку. Этот механизм пригодится для титульных страниц, договоров, карточек товара, справочников версий и других документов с повторяющимися реквизитами.

Контекстные пары связывают пояснение со списком или отдельным блоком

В новой спецификации появилось понятие контекстной пары. Оно объединяет два соседних элемента, где первый подготавливает смысл второго. Такой связкой может быть абзац и последующий список, два последовательных абзаца либо абзац и блочное включение.

Пример выглядит привычно:

Для установки потребуются три компонента:

- Python
- Git
- текстовый редактор

Человек сразу понимает, что список продолжает предыдущее предложение. Парсеру эта связь тоже полезна. Он может сохранить блок как единое смысловое целое, корректно перенести его между страницами и подобрать оформление, при котором вводная строка не окажется отдельно от списка.

Контекстные связи важны для учебников, инструкций и справочных материалов. В них короткое утверждение часто раскрывается таблицей, формулой, примером кода или предупреждением. Явная модель документа упрощает преобразование в HTML и помогает будущим инструментам анализировать содержимое без догадок по внешнему виду.

Markvan поддерживает автоматические агрегаторы. Из размеченных сущностей можно собрать оглавление, глоссарий или другой сводный блок:

{§toc Оглавление
§}

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

Конвертер строит дерево документа и выпускает только используемые ресурсы

Новый конвертер написан на Python и работает через промежуточное дерево объектов. Сначала программа читает конфигурацию и исходные .text-файлы, затем отделяет метаданные, подключает импорты и преобразует разметку в абстрактную структуру.

В дереве представлены документ, разделы, заголовки, абзацы, списки, сноски, ссылки, контекстные пары и включения. После разбора агрегатор нормализует пути, нумерует элементы и собирает данные для меню или оглавления. Финальный этап превращает дерево в HTML либо другой поддерживаемый формат.

Архитектура полезна для расширения проекта. Новый экспортёр может работать с уже разобранным деревом и не заниматься повторным анализом синтаксиса. Теоретически это открывает путь к EPUB, FB2, DOCX и другим форматам. На странице загрузки сейчас подтверждена работа над HTML и PDF, а остальные направления находятся на ранней стадии.

При генерации сайта конвертер копирует только те изображения и документы, которые упомянуты в исходниках. Стили и сценарии подключаются по фактически используемым элементам. Страница без формул не требует библиотеки для их отображения, а проект без видео не получает лишний медиакод.

Для Visual Studio Code опубликовано расширение с подсветкой синтаксиса. Оно выделяет элементы Markvan, проверяет пути к файлам, позволяет переходить по локальным ссылкам и показывает предварительный просмотр изображений. Установка пока выполняется вручную через папку расширений VS Code.

Markvan охватывает задачи, для которых Markdown приходится расширять

Markdown хорошо подходит для README, заметок, статей и базовой документации. Его компактный синтаксис знаком разработчикам, редакторам и пользователям систем управления контентом. Markvan ориентирован на более сложную модель произведения, где нужны издательские и учебные сущности.

Сравнение основных возможностей выглядит так:

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

Выбор зависит от жизненного цикла текста. Для репозитория на GitHub, короткой инструкции или статьи в распространённой CMS Markdown обычно проще. Для экспериментальной системы хранения книг, курсов и научных материалов Markvan даёт больше специализированных конструкций в исходном формате.

Бета-статус ограничивает применение в рабочих и архивных проектах

На странице загрузки опубликован Markvan Converter 0.8 от 10 июля 2026 года. Автор прямо указывает, что программа находится в бета-стадии, не прошла полное тестирование и может обрабатывать отдельные конструкции с ошибками. Исходный код конвертера и расширения VS Code доступен через раздел загрузки проекта.

Эти ограничения особенно существенны для документов, которые нельзя потерять или исказить:

• юридических договоров;
• научных публикаций с формулами и ссылками;
• учебных материалов с автоматической проверкой;
• крупных технических руководств;
• архивов, рассчитанных на долгосрочное хранение.

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

Лицензирование инструментов тоже требует внимания. Официальная страница разрешает бесплатное использование программ для персональных, некоммерческих проектов и сайтов малого бизнеса. Продажа программ и применение в автоматизированных онлайн-сервисах ограничены, а коммерческие разрешения оформляются отдельно. Эти условия нужно изучить до включения конвертера в платный продукт или SaaS-платформу.

Зрелость спецификации и зрелость инструментария находятся на разных уровнях. Язык уже описывает широкий набор сущностей, а редакторы, плагины, тесты и экспортёры продолжают формироваться. Проекту потребуется сообщество пользователей, обратная совместимость версий и набор эталонных тестов, чтобы его можно было уверенно применять в больших производственных системах.

Тестовый проект покажет, подходит ли Markvan для вашей схемы публикации

Начать знакомство лучше с небольшого материала на 5–10 страниц. Для проверки подойдёт инструкция, учебная глава, личный справочник или мини-сайт с несколькими разделами. Такой объём позволяет изучить базовый синтаксис и увидеть реальные ограничения без переноса большого архива.

Рабочая последовательность выглядит так:

1. Откройте быстрый старт Markvan и подготовьте один .text-файл.
2. Добавьте название, два уровня заголовков, список, ссылку и изображение.
3. Установите подсветку для VS Code, если этот редактор уже используется в работе.
4. Скачайте конвертер 0.8 и создайте отдельную тестовую сборку.
5. Сравните исходный текст с полученным HTML.
6. Зафиксируйте конструкции, которые требуют ручной правки или дополнительного шаблона.
7. Храните исходники в Git, чтобы видеть изменения и быстро возвращаться к рабочей версии.

Markvan интересен как попытка создать единый читаемый исходник для книг, документации, учебных курсов и статических сайтов. Его сильная сторона — подробная семантическая модель текста. Практическое применение в 2026 году разумно начинать с пилотного проекта: спецификация уже даёт материал для серьёзного эксперимента, а бета-конвертер пока требует контроля результата.