Коротко о markvan-разметке текстов

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

Многие знакомы с markdown-разметкой, которая позволяет подготавливать небольшие простые тексты для последующей конвертации в html. Теперь появился более современный инструмент с расширенными возможностями — markvan. Маркван предназначен для написания полноразмерных литературных и технических текстов.

Как возникла идея

В эпоху стремительного, даже безумного, развития информационных технологий, требующих применения всё большого количества языков, стандартов, фреймворков и подходов, иногда хочется чего-то простого… более надёжного и понятного. Хочется долговечного, не зависящего от популярных в настоящее время программ. Программы и форматы сменяют друг-друга: txt, doc, docx, gdoc, rtf, odt и т.д. При этом форматирование и содержание страдает при смене программного обеспечения.

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

Я человек очень ленивый, поэтому, очередной раз внося изменения в проект, решил кардинально поменять подход к проблеме.

Описание задачи

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

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

О проекте

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

Довольно быстро получилось придумать основу новой системы разметки текстов, которая меня почти устраивала. В ней удалось достичь некоей системности и согласованности. Оставил идею годик отлежаться и вернулся к ней только на этих новогодних каникулах. Разметка проработана не до конца, процентов на 70-80, но чтобы двигаться дальше нужно с кем-то ею поделиться. Разметка называется Маркван, ознакомиться с ней можно на сайте markvan.mudrium.ru, там же есть ссылка на телеграм-канал для обсуждений.

О разметке маркван

Базовая маркван-разметка выглядит довольно ожидаемо. Для заголовков используется несколько символов образующих линию, например, привычные вам знаки равно и минус. Однако, помимо текстовых заголовков, добавляется возможность разметить части и главы произведения. Выделение жирным привычно двумя звёздочками и т.п. Вот пример простой маркван-разметки:

***
Мой первый рассказ



"""
Глава I
Неизвестная планета


===
Удачная находка

Прежде, чем начать своё повествование, расскажу вам весьма интересную, но **жуткую** историю про переселенцев в Калахари.

Название стоит особняком - оно выделяется звёздочками, что интуитивно пересекается с выделением жирным. Далее части и главы выделяются вертикально направленными чёрточками ^^^ и """, а текстовые горизонтальными ===, ---, ..., а меньшие подзаголовки используются реже и не стоят упоминания.

Сноски и ссылки

Отдавая дань традициям, маркван-разметка позволяет размечать сноски. Можно использовать звёздочки или цифры.

Некий текст со звёздочковой[***] и цифровой[*5] сносками.
|*** Вот текст сноски, его можно разместить где угодно.
|*5 При конвертации останется только цифра.

По аналогии создаются ссылки.

А это текст со ~[ссылкой]~, адрес которой должен находиться в следующей строке.
|~ example.com (Пример гиперссылки)

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

Включения

Это довольно интересная особенность маркван-разметки.

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

Для всех включений выработан единый синтаксис, когда сам текст включения обрамляется парами из квадратной скобки и символом признаком включения.

Вот, чтобы получить такой результат:

Достаточно ввести такой текст

[[ Схема строения сердца
>Схема сердца.jpg
]] 1. Левая общая сонная артерия. 2. Левая аортная подключичная артерия. 3. Аорта. 4. Левые лёгочные артерии. и т.д.

Включения бывают нескольких типов:

• [( )] текстовый блок;
• [= =] преформатированный текст;
• [& &] программный код;
• [% %] формулы;
• [| |] таблицы;
• [/ /] комментарии;
• [[ ]] медиа-включение;

Для включения можно указать класс, идентификатор, название включения, и его описание.

[(class #id Name
Тело включения
)] Description

Причём, ряд классов уже зарезервирован и имеет знаковый синоним для короткого написания, например, !! — warning.

А ещё текстовые включения могут содержать в себе другие включения:

[(i Это интересно!
Когда Верроккьо получил заказ на картину, на которой надлежало изобразить двух ангелов, одного он нарисовал сам, а рисование второго поручил своему юному ученику. Когда да Винчи справился с работой лучше него, Верроккьо был так потрясён его талантом, что навсегда завязал с живописью, заявив, что своего ученика ему никогда не превзойти.
[[
>davinci.jpg (Фото Леонардо да Винчи)
]]
)]

Строковые включения

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

Пример однострочного условия &[rez = a + b if a < b else a - b]& в языке программирования python.

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

Работа продолжается

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

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

Маркван-сайт

Побочным продуктом размышлений стал маркван-сайт. Я подумал, вот у меня html, но теперь нужно его копировать и куда-то вставлять. А нельзя-ли сделать так, чтобы сайт получался сам собой? Ведь что такое сайт в традиционном его понимании — это просто несколько страничек плюс навигация по ним. Отдельно можно приложить шаблон, стили, яваскрипт. Ну и попробовал — опять получилось.

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

Кстати, сам сайт о маркван-разметке сформирован по этой технологии. Изначально были созданы текстовые файлы и разложены по папкам. Не делалось никаких описей структуры и какой-либо другой дополнительной работы. Чтобы создать сайт потребовалось нажать 3 кнопки: выбор источника, выбор места сохранения и старт. Для обычного пользователя не нужно устанавливать на компьютер питон, не нужно идти в командную строку и что-то там колдовать, не нужно вникать в yaml или что-то подобное. Пусть это довольно ограниченный по возможностям способ создания сайта, но как по мне, способ довольно простой и изящный в своей простоте.

Надеюсь у вас возникнет желание попробовать маркван-разметки и сделать себе маркван-сайт. В таком случае жду обратную связь для доработки стандарта и программ конвертации.

Кстати, вот пример сайта созданного с помощью Марквана: Учитель из замирья.