# Документы

← [К разделу «Как собирается сайт»](README.md)

Документ — конкретная страница, запись, статья или товар. Его структура задаётся
рубрикой, а внешний вид — шаблоном рубрики и шаблоном сайта.

## Создание документа

1. Откройте **Контент → Документы** и нажмите создание.
2. Сначала выберите рубрику. От неё зависят поля, группы, значения по умолчанию,
   шаблон URL и права.
3. Заполните название, адрес, SEO и поля содержимого.
4. Проверьте JSON-предпросмотр данных без сохранения, если нужно увидеть полный
   payload документа.
5. Сохраните черновик или опубликуйте документ.

Рубрику существующего документа нельзя свободно поменять: у другой рубрики иной
набор полей и правила хранения. Такой перенос выполняется отдельной миграцией.

## Состояния

| Состояние | Что означает |
| --- | --- |
| Опубликован | Попадает в публичные листинги и доступен по прямому URL. |
| Выключен | Исключён из листингов, но доступен по известному прямому URL. |
| Вне срока | При включённой проверке дат ещё не опубликован либо уже истёк; гостю возвращается 404. |
| Удалён | Находится в корзине, гостю возвращается 404 и может быть восстановлен. |
| Окончательно удалён | Документ и его значения удаляются без восстановления через список. |

Главная страница и назначенная страница 404 защищены от удаления. Для документа
№1 нельзя изменить корневой адрес `/`.

Проверка дат управляется настройкой `use_doctime`. Когда она выключена, даты
начала и окончания остаются информационными. Когда включена, окно применяется и
к листингам, и к прямому URL. Авторизованный администратор может открыть удалённый
или находящийся вне срока документ на сайте, но увидит предупреждение; обычному
посетителю отдаётся штатная страница с HTTP 404.

## Адрес и редиректы

Полный URL собирается из шаблона рубрики и короткого alias документа. Например,
шаблон `news/%Y/%m` и alias `new-office` дают
`/news/2026/07/new-office`.

- короткий alias должен быть уникален в своём поддерживаемом контракте;
- полный путь нельзя занять, если им уже владеет документ, редирект или публичный
  маршрут модуля;
- при изменении адреса история alias может создать постоянный редирект;
- общая история доступна в **Документы → Редиректы**, история конкретной страницы
  — из её редактора;
- 301 и 308 используются для постоянного переноса, 302 и 307 — для временного.

Не создавайте новый документ на старом адресе, пока редирект нужен поисковым
системам и внешним ссылкам.

## Поля и данные

Редактор показывает только поля выбранной рубрики. Порядок, группы, ширина,
обязательность, значение по умолчанию, префикс и суффикс задаются в конструкторе
рубрики. Сам тип поля определяет редактор, валидацию, хранение и публичный вывод.

Данные документа доступны:

- в шаблоне рубрики через `[tag:fld:alias]`;
- в запросах и фильтрах по alias поля;
- через JSON API документа;
- в hooks до и после сохранения;
- в нативном snapshot, который объединяет документ и его поля.

## SEO и анонс

Название документа не заменяет все SEO-поля. Отдельно проверяйте title,
description, robots, canonical, Open Graph и заголовок хлебных крошек.

Анонс — короткое самостоятельное представление документа для списков, карточек,
поиска и публикаций. Если проект строит анонс из полей или шаблона запроса, поле
можно оставить пустым; не копируйте туда полный основной текст.

## Сохранение, ревизии и snapshot

Обычное сохранение закрывает редактор, **Сохранить и остаться** оставляет его
открытым. `Ctrl+S` выполняет именно сохранение с продолжением работы.

Новые ревизии сохраняют основные настройки документа и все значения полей.
Старые снимки формата «Только поля» остаются совместимыми. Перед восстановлением
создаётся резервная ревизия текущего состояния; ID и рубрика не меняются.
Snapshot публичных данных обновляется после сохранения и может быть пересобран
вручную из раздела документов.

Форма также хранит локальный черновик в текущем браузере и защищена номером
версии. Если документ уже изменён в другой вкладке, старая форма не перезапишет
новые данные: её можно сохранить локально, обновить страницу и восстановить для
ручного объединения. Подробно: [Content Studio](content-studio.md).

Кнопка **На сайте** у выбранной ревизии открывает её в реальном шаблоне рубрики.
Ссылка подписана текущей сессией на пять минут и работает только для сотрудника с
правом `manage_documents` и правом редактирования этой рубрики. Preview не читает
и не записывает compiled/full-page cache, не увеличивает просмотры, получает
`noindex` и `no-store`. Не формируйте параметры `revision_preview`,
`preview_token` или старый `revission` вручную: без подписи они возвращают 403.

## Проверка после изменения

1. Откройте публичный URL в новой вкладке.
2. Проверьте шаблон рубрики, поля, изображения и навигацию.
3. Проверьте title, description, canonical и Open Graph в исходном HTML.
4. При смене URL откройте старый адрес и убедитесь в редиректе.
5. Для документа в каталоге проверьте обновление его проекции и фильтров.