Frontmatter-патчи

У вас 200 заметок в папке blog/, и каждой нужно прописать free: true. Или вы хотите, чтобы все заметки в docs/ открывались на поддомене docs.mysite.com. Руками это делать бессмысленно, а через патчи вы пишете одно правило и оно применяется ко всей папке.

Frontmatter-патч работает так: вы указываете паттерн путей и выражение, которое добавляет или меняет свойства заметок. Система применяет патч при загрузке, до рендеринга страницы. Заметки остаются чистыми, в их frontmatter ничего не меняется.

Кому подходит

У вас раздел с бесплатным контентом и раздел с платным, а каждый раз прописывать free вручную надоело
Вы хотите назначить layout целой папке, а не каждой заметке отдельно
Вам нужно привязать поддомен к разделу сайта через маршруты

Как создать патч

Патчи создаются в админке, в разделе Заметки и контент. Каждый патч состоит из трёх частей:

Паттерны путей — к каким заметкам применять. Поддерживаются * (один уровень вложенности) и ** (рекурсивно)
Выражение — что добавить или изменить в свойствах
Приоритет — порядок применения, если патчей несколько

Пример с сайта trip2g.com:

Примеры

Сделать все заметки в blog/ бесплатными:

паттерн: blog/*
выражение: { free: true }

Каждая заметка в папке blog/ получит free: true, даже если во frontmatter этого нет.

Назначить layout для раздела:

паттерн: blog/*
выражение: { layout: "blog_layout" }

Все заметки в blog/ будут использовать шаблон blog_layout, а остальные возьмут тот, что указан у них во frontmatter или в настройках сайта.

Привязать папку к поддомену:

паттерн: docs/**
выражение: { route: "docs.mysite.com" }

Все заметки в docs/ и вложенных папках автоматически окажутся на docs.mysite.com. Подробнее о маршрутах читайте в мультидоменах.

Добавить суффикс к заголовкам:

паттерн: *
выражение: meta + { title: meta.title + " — My Site" }

Здесь используется переменная meta, которая содержит текущие свойства заметки. Выражение берёт существующий заголовок и добавляет к нему название сайта.

Условный патч — поставить layout, только если он не задан:

паттерн: *
выражение: if std.objectHas(meta, "layout") then {} else { layout: "default" }

Если в заметке уже прописан layout, патч ничего не трогает. Если нет, ставит default.

Приоритеты и цепочки

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

Допустим, у вас два правила:

Приоритет	Паттерн	Выражение
0	`*`	`{ layout: "default" }`
10	`blog/*`	`{ layout: "blog_layout" }`

Для заметки blog/post.md сначала применится правило с приоритетом 0 и поставит layout: "default". Потом правило с приоритетом 10 перезапишет его на blog_layout. Итого заметка получит blog_layout, а все остальные заметки останутся с default.

Паттерны

Паттерны определяют, к каким заметкам применится патч. Синтаксис похож на .gitignore, но с некоторыми особенностями.

Спецсимволы:

Символ	Что делает
`*`	Любая последовательность символов, кроме `/`. Не матчит скрытые файлы (начинающиеся с `.`)
`**`	Любое количество вложенных папок, включая ноль
`?`	Ровно один символ, кроме `/`
`[abc]`	Один символ из набора: `a`, `b` или `c`
`[a-z]`	Один символ из диапазона
`[^abc]` или `[!abc]`	Любой символ, кроме указанных
`{foo,bar}`	Один из вариантов: `foo` или `bar`

Примеры:

Паттерн	Матчит	Не матчит
`blog/*`	`blog/post.md`, `blog/draft.md`	`blog/2024/post.md` (вложенная папка)
`blog/**`	`blog/post.md`, `blog/2024/jan/post.md`	`docs/post.md`
`blog/*/draft`	`blog/draft1.md`, `blog/2024/drafts/draft-new.md`	`blog/final.md`
`*`	`index.md`, `about.md`	`.hidden.md`, `blog/post.md`
`*.md`	`about.md`, `index.md`	`.secret.md`
`.*`	`.hidden.md`, `.config.md`	`about.md`
`blog/post-?.md`	`blog/post-1.md`, `blog/post-a.md`	`blog/post-12.md`
`{blog,docs}/*`	`blog/post.md`, `docs/api.md`	`notes/post.md`
`blog/[0-9]*`	`blog/2024-review.md`	`blog/my-post.md`

Нюансы, которые стоит знать:

** работает только между разделителями пути. Паттерн blog/**/*.md поймает все .md-файлы на любой глубине внутри blog/. А вот blog/**.md сработает так же, как blog/*.md, то есть только на первом уровне. Если нужна рекурсия, пишите blog/**/*.md.

Скрытые файлы (начинающиеся с точки) не попадают под * и ?. Чтобы поймать их, используйте явный паттерн .* или конкретное имя .config.

Пустые альтернативы в фигурных скобках работают как опциональные части: some{thing,} матчит и something, и some.

Include и exclude:

У каждого патча есть include-паттерны (к чему применять) и exclude-паттерны (что исключить). Заметка попадает под патч, если подходит хотя бы под один include и не подходит ни под один exclude.

include: ["blog/**"]
exclude: ["blog/drafts/*"]

Этот патч применится ко всем заметкам в blog/, кроме тех, что лежат в blog/drafts/.

Выражения на Jsonnet

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

Доступные переменные:

Переменная	Тип	Что содержит
`meta`	объект	Текущие свойства заметки (после предыдущих патчей в цепочке)
`path`	строка	Путь к файлу, например `"blog/my-post.md"`

Выражение должно вернуть объект {}. Его содержимое добавляется к свойствам заметки. Если ключ уже существует, он перезаписывается.

Простой объект — самый частый случай. Выглядит как JSON:

{ free: true, layout: "blog" }

Чтение текущих свойств через переменную meta:

meta + { title: meta.title + " — My Site" }

Оператор + для объектов работает как merge: берёт все поля из meta и перезаписывает title новым значением.

Условия через if / then / else:

if std.objectHas(meta, "layout") then {} else { layout: "default" }

Здесь std.objectHas проверяет, есть ли у заметки поле layout. Если есть, патч возвращает пустой объект (ничего не меняет). Если нет, ставит default. Без проверки через std.objectHas обращение к meta.layout упадёт на заметке, где этого поля нет.

Логика на основе пути:

if std.startsWith(path, "premium/")
then { free: false }
else {}

Хотя это можно решить паттернами ["premium/*"], бывают случаи, когда условие удобнее выразить через путь прямо в выражении.

Конкатенация строк через +:

{ description: meta.title + " — опубликовано на " + meta.site_name }

Форматирование строк через % (как в Python):

{ og_title: "%s | %s" % [meta.title, "My Site"] }

Полезные функции стандартной библиотеки:

Функция	Что делает	Пример
`std.objectHas(obj, key)`	Проверяет наличие поля	`std.objectHas(meta, "layout")`
`std.length(x)`	Длина строки или массива	`std.length(meta.title) > 50`
`std.startsWith(str, prefix)`	Начинается ли строка с	`std.startsWith(path, "blog/")`
`std.endsWith(str, suffix)`	Заканчивается ли строка на	`std.endsWith(path, ".draft.md")`
`std.split(str, delim)`	Разбивает строку	`std.split(path, "/")`
`std.join(delim, arr)`	Склеивает массив	`std.join(", ", meta.tags)`

Составной пример — premium-раздел с дефолтной сложностью:

meta + {
  free: false,
  reading_complexity:
    if std.objectHas(meta, "reading_complexity")
    then meta.reading_complexity
    else "advanced"
}

Патч закрывает доступ к заметкам (free: false) и ставит reading_complexity: "advanced", но только если автор не указал сложность вручную.

Пустой объект {} — возвращайте его, когда патч не должен ничего менять. Это полезно в ветке then или else условия.

Что может пойти не так

Патч не применяется. Проверьте паттерн: blog/* не поймает blog/drafts/post.md, для вложенных папок нужен blog/**.

Ошибка в выражении. Если выражение падает на конкретной заметке (например, обращается к несуществующему полю), патч пропускается только для этой заметки. Остальные заметки обработаются нормально, сайт не сломается.

Два патча конфликтуют. Побеждает тот, у кого выше приоритет (большее число). При одинаковом приоритете побеждает созданный позже.

Забыли про порядок. Патч с приоритетом 10 видит meta после всех патчей с приоритетом 0-9. Если вы добавляете суффикс к title в патче с высоким приоритетом, он возьмёт уже изменённый заголовок.

Обращение к несуществующему полю. meta.tags упадёт, если у заметки нет поля tags. Оборачивайте в проверку: if std.objectHas(meta, "tags") then meta.tags else [].