Всё и сразу

§1.1Строчная разметка

Разбор выделения дружелюбен к CJK: жирный закрывается даже вплотную к китайской пунктуации — **报文。**同时 отрисовывается как 报文。同时, а не как буквальные звёздочки. Курсив, зачёркивание и строчный код работают как обычно; с переключателем gemoji шорткод вроде :sparkles: превращается в ✨. Символы внутри строчного кода не участвуют ни в каком разборе, поэтому обратные кавычки — безопасный способ показать синтаксис: **, $…$ и > [!note] появляются буквально. Чтобы показать в прозе саму звёздочку, экранируйте её — *вот так* останется просто текстом.

§1.2Вики-ссылки

С включённым переключателем wikilinks ссылки [[в двойных скобках]] разрешаются по коллекции заметок, как и положено вики: по id (design-tokens — со страницы русского зеркала ссылка сперва ищет зеркало того же языка и лишь потом падает на английский оригинал), по псевдониму (boundaries приводит к заметке с id three-way-split), с подписью (руководство по быстрому старту). Цель, которая ни во что не разрешилась, отрисовывается помеченной мёртвой ссылкой, а не роняет сборку — о гнили ссылок докладывает движковый check-wikilinks в CI, где ей и место.

§1.3Таблицы: в ширину — прокрутка, в узком месте — карточки

Таблица от шести столбцов в узком контейнере должна перекладываться по строке на карточку, а не сжимать каждую ячейку до двух букв. Эта семиколонная таблица — одновременно шпаргалка по вариантам callout и живая проверка той самой переклейки (сузьте окно до ширины телефона):

Заголовки по умолчанию английские; сайт меняет весь набор через опцию calloutLabels в siteMarkdown, например calloutLabels: { tip: 'Интуиция' }. Заголовок, написанный прямо в цитатном синтаксисе (> [!tip] Мой заголовок), побеждает всегда.

§2.1Callout: три написания

Первое — цитатный синтаксис в духе Obsidian и GitHub (доступен при callouts: true, работает и в чистых Markdown-файлах):

Метка сворачивания из Obsidian тоже работает: > [!note]- отрисовывается свёрнутым, > [!note]+ — раскрытым:

Второе — компонент пакета в MDX (astro-inkstone/components/Callout.astro, импорт по пути). Без title он показывает подпись варианта по умолчанию — ту же, что у цитатного синтаксиса:

Третье — сырой HTML, все шесть вариантов подряд (один к одному с правилами .callout в base.css):

§2.2Математика

Строчные формулы стоят прямо в тексте: оптическая толща записывается как $\tau = \int \kappa \rho \, \mathrm{d}s$. Выключная математика требует трёхстрочной формы ($$ на отдельных строках) — однострочную контроль отклоняет: она молча отрисовалась бы мелкой строчной формулой:

Фон формул — нарочно другая бумага, чем у основного текста, и меняется вместе с темой. И к слову: экранируйте долларовые цены в прозе — этот кофе стоит $3.

§3.1Рамки для кода

Ограда с title="…" получает строку заголовка с именем файла; кнопка копирования в углу — общесайтовая. Построчные пометки [!code ++] / [!code --] отрисовываются диффными фонами:

def build_pipeline(opts):
    plugins = [remark_math]  
    plugins = [remark_gemoji, remark_math]  
    return assemble(plugins, guard=opts.guard)

Рамка с пометкой collapse рождается свёрнутой и занимает место только раскрытой — самое то для длинных конфигов:

site:
  markdown:
    numbering: chapters
    math: true
    codeFrame: true
    mermaid: true
    callouts: true
    wikilinks: true
  styles:
    - astro-inkstone/styles/tokens.css
    - astro-inkstone/styles/base.css

Двухтемная подсветка — от shiki, который выдаёт оба набора цветов разом; base.css выбирает нужный по data-theme в одном-единственном месте, без перетягивания специфичности.

§3.2Диаграммы mermaid

Ограда ```mermaid на этапе сборки оставляет лишь заглушку; рендерер подгружается динамически и только на страницах с диаграммой (страницы без неё не платят ничего), а при смене темы диаграмма перерисовывается:

flowchart LR
  A["astro-inkbrush<br/>движок: правка / диалект / контроль"] --> C["ваш сайт<br/>айдентика / маршруты / деплой"]
  B["astro-inkstone<br/>бумага: токены / стили / конвейер"] --> C
  A -. диалект — один на двоих .-> B

§3.3Дополнения GFM

Списки задач и сноски приезжают вместе с GFM:

• токены импортированы
• base.css импортирован
• палитра айдентики переопределена

Утверждение, которому нужен источник, получает сноску.¹

§4.1Что контроль отклоняет на этой странице

То, что эта страница собирается, само по себе доказывает: всё показанное выше написано правильно. А вот эти написания уронили бы сборку на месте (попробуйте одно, затем npm run build):

• маркер выделения без пары — например, **, оставшаяся незакрытой в конце строки;
• однострочный $$x$$ (нужна трёхстрочная форма);
• ручная нумерация заголовков: назови мы этот раздел ## 9. Что контроль…, номер столкнулся бы с нумерацией времени сборки и был бы отловлен;
• MDX, вычисляющий фигурные скобки в прозе: {0,1,2,3} отрисовался бы просто как 3, поэтому контроль требует экранированной формы {0,1,2,3};
• формула, которую KaTeX не может отрисовать (контроль сам прогоняет каждую формулу в строгом режиме, вместо того чтобы выпускать на страницу красный текст ошибки).