Поділ натроє

§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 одним рядком, перемикачі описано у «Швидкому старті»;
• компоненти під astro-inkstone/components/, імпортовані за шляхом у міру потреби;
• фабрику таксономії та будівник зворотних посилань під astro-inkstone/lib/, прив’язані до власного реєстру сайту;
• у режимі WIKI — повну CMS рушія (спробуйте на цьому сайті: npm run wiki);
• п’ять перевірок: check-content, check-wikilinks і check-dist (їдуть із рушієм), ui_probe і contrast_probe (живуть тут) — див. checks.

Кожен ефект рендерингу на кожній сторінці цього саду — наслідок саме цього поділу: нотатки — це посібник, а посібник — це демо.