🗂️ Реестры проекта: руководство для редакторов и разработчиков

Для кого эта документация: для контент-менеджеров (гуманитариев) и разработчиков, помогающих вести мемориальный проект. Экспертиза не требуется — сложные вещи объясняем простым языком.

Последняя сверка с кодом: src/data/authors.yaml, src/content.config.ts (Astro 6.x), ветка main-qwen3.

1. Введение: Философия реестров

1.1. Единый источник правды (Single Source of Truth)

1
2
3
4
5

1.2. Три главных реестра проекта

1.3. ⚠️ Главный принцип: неинвазивность (Non-destructive approach)

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

2. Подробный гайд по authors.yaml

2.1. Структура файла

yaml
1
2
3
4
5

yaml
1

2.2. Поле type и зависимость набора полей

schema_type — техническое имя схемы Schema.org (Person / Organization). Он должен согласовываться с type: персона → Person, все остальные → обычно Organization.

2.3. Строгая уникальность id

1. id не повторяется внутри файла. Две записи с одинаковым id = ошибка сборки (Duplicate entry id) — Astro не соберёт контент.
2. id не повторяется между всеми файлами реестров. Когда появятся units.yaml и cemeteries.yaml, идентификаторы должны быть уникальны и между ними тоже. Если редакция совпадает с одноимённым сообществом — придумайте разные ключи: redaktsiya-lenino vs soobshchestvo-lenino.
3. Формат id: строчные латинские буквы, цифры и дефисы (транслит): ak-monay, nevzorov-b-i, redaktsiya. Без пробелов, точек, кавычек и кириллицы.
4. id неизменяем после публикации. Переименовали — порвали все ссылки. Если запись ошибочна — лучше создать новую с новым id, а старую пометить в note.

3. Технический нюанс: даты и «умный» парсинг YAML

3.1. Феномен smart parsing

yaml
1

1

3.2. Наше решение: z.preprocess

ts
1
2
3
4
5
6

3.3. ✅ Правило: даты пишем строго БЕЗ кавычек

yaml
1
2

4. Правила заполнения пустых значений

yaml
1
2
3

Лайфхак: скопируйте последнюю запись того же type, вставьте ниже, замените значения. Канон не сломается, опечаток в именах полей не будет.

5. Реестры units.yaml и cemeteries.yaml — зарегистрированы и работают

1. YAML-файлы в src/data/ — тот же формат «массив записей с id».
2. В content.config.ts — отдельные defineCollection (unitSchema, cemeterySchema) с изолированными loader'ами (glob({ pattern: 'units.yaml', base: './src/data' })). Оригинальные коллекции шаблона (posts/about) не тронуты — принцип неинвазивности соблюдён.
3. Уникальность id — глобальная, через все три реестра (см. п. 2.3).
4. Даты — общий helper isoDate() (z.preprocess: Date → строка YYYY-MM-DD).
5. Документальные позиции не меняем. Поля, где источник даёт «строку, похожую на число» (passport_number с слэшем 82-289/2023, obd_document_id, buried_known/unknown), защищены z.preprocess от number→string; значения из CSV переносятся символ в символ.
6. Внешние ссылки на сервисы МО РФ (obd-memorial.ru, memmo.ru): официальное предупреждение Минобороны требует российских сертификатов / корневого сертификата Минцифры. Поэтому: ссылка хранится как есть + метка [Минцифры] в note; автоматическая проверка доступности при сборке НЕ делается; карточка самодостаточна (данные CSV дублируются в полях).

5.1. Фактические поля units.yaml (схема unitSchema)

5.2. Фактические поля cemeteries.yaml (схема cemeterySchema)

5.3. Как контент-менеджер связывает сущности

yaml
1
2
3
4
5
6
7

⚠️ Ссылки «мягкие» (soft resolve): несуществующий ID не должен ронять сборку — компонент просто проигнорирует его и выведет предупреждение. Так защищает нас от опечаток редактора.

6. Словарь типичных ошибок (перевод на человеческий)

1. Прочитайте сообщение целиком — там указаны файл, запись и поле.
2. Откройте указанный файл и найдите запись по id из сообщения.
3. Сравните с соседней «рабочей» записью того же типа.
4. После правки: npm run build (или npx astro check) — сборка должна пройти молча.

Приложение А. Готовая шапка-шпаргалка для authors.yaml