Тройное разделение

§1Три слоя — три владельца

• astro-inkbrush (движок): минимальная CMS — правка блоков прямо в браузере, поблочная история версий с откатом, комментарии, ИИ-вопросы, переписывание и перевод, импорт из инбокса. Ему же принадлежит одна вещь, которая на первый взгляд не должна принадлежать CMS: диалект Markdown и контроль контента. Причина жёсткая: грамматика, которую принимает редактор, и грамматика, которую отрисовывает страница, обязаны быть одной и той же — иначе «в редакторе сохранилось, на странице сломалось» лишь вопрос времени. Поэтому правила парсера написаны один раз, в движке, и потребляются в трёх местах: отрисовка сайта, валидация сохранений CMS, проверки CI.
• astro-inkstone (бумага — этот пакет): общий слой внешнего вида и конвейера — двухуровневые дизайн-токены в двух контекстах, таблица стилей контента base.css и полка browse.css, библиотека компонентов, пресет конвейера siteMarkdown, помощники таксономии и обратных ссылок, на которых работает этот сад, сабсет кодового шрифта Maple Mono CN и зонды слоя отрисовки. Айдентикой сайта он не занимается: фирменные цвета, обвязка макета, маршруты и деплой — не его дело.
• Сайт (например, сад, который вы читаете): переопределяет токены первого уровня под свой фирменный цвет; владеет собственным сайдбаром и обвязкой навигации (реализация этого сайта — образцовый ответ); решает, как организован контент, как выглядят маршруты и куда всё деплоится.

Одна строка на память: движок редактирует, бумага задаёт облик, сайт — это вы.

§2Почему границы проходят именно здесь

За каждым разрезом — настоящее ограничение.

Диалект принадлежит движку, потому что проверка с иным набором плагинов, чем у сайта, хуже, чем никакой проверки: без плагина математики она примет фигурные скобки формул за выражения JSX, без GFM пропустит табличные вертикальные черты. Грамматика написана однажды и потребляется в трёх местах — разъехаться ей просто не с чем.

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

Айдентика принадлежит сайту, потому что стоит общему слою впитать фирменный цвет одного сайта, как всем остальным приходится отбиваться от него переопределениями. Отсюда двухуровневые токены: сайт переопределяет сырую палитру первого уровня (--p-*), а семантический и компонентный слои следуют за ней нетронутыми — см. design-tokens.

§3Где сидит механика навигации

Та же дисциплина — у того, по чему вы сейчас перемещаетесь. Пакет поставляет механику: createTaxonomy (разрешение типов, направлений и тегов, наследование от хаба, локальные зеркала), createBacklinks (индекс обратных ссылок) и презентационные компоненты вроде карточек заметок и рядов рубрик на главной. Сайт владеет словарём и маршрутами: типы и направления этого сада живут в его собственном файле-реестре, а страницы /kind/…, /domain/…, /tag/… — обычные страницы Astro, которые потребляющий сайт копирует и перекраивает под себя. То же разделение, этажом выше: механика в пакете, смысл на сайте.

§4Что получает сайт

С точки зрения сайта, этот пакет вместе с движком дают:

• astro-inkstone/styles/tokens.css + base.css + browse.css: токены, затем колонка чтения, затем полка — три строки @import на весь облик;
• siteMarkdown(...): весь конвейер Markdown одной строкой, переключатели описаны в getting-started;
• компоненты в astro-inkstone/components/, импортируемые по пути по мере надобности;
• фабрику таксономии и построитель обратных ссылок в astro-inkstone/lib/, привязанные к реестру самого сайта;
• в режиме WIKI — полную CMS движка (попробуйте на этом сайте: npm run wiki);
• пять проверок: check-content, check-wikilinks и check-dist (едут с движком), ui_probe и contrast_probe (едут здесь) — см. checks.

Каждый эффект отрисовки на каждой странице этого сада — плод именно этого разделения: заметки и есть руководство, а руководство и есть демо.