Профили страниц
Профиль говорит, какого типа страница: инструкция, справочник, лендинг и так
далее. По профилю docara validate page проверяет, есть ли у страницы нужные
части, например нумерованные шаги у инструкции, и выдаёт список вопросов для
редактора. Проверка ничего не меняет в Markdown, не обращается к ИИ и не
останавливает сборку.
Профили необязательны. Без файла docara.authoring.json и без profile во
front matter страницы не проверяются.
Файл docara.authoring.json
Файл лежит в корне проекта рядом с docara.json:
{
"schema": "docara.authoring.v1",
"default_profile": "article",
"rules": [
{"match": "index.md", "profile": "landing"},
{"match": "start.md", "profile": "tutorial"},
{"match": "reference/**", "profile": "reference"},
{"match": "development/architecture.md", "profile": "explanation"}
]
}
| Поле | Что задаёт |
|---|---|
schema |
Тип файла. Всегда docara.authoring.v1. |
default_profile |
Профиль страниц, которым не подошло ни одно правило. Без него такие страницы не проверяются. |
rules |
Правила: какой профиль у страниц по пути. |
rules[].match |
Путь к файлу страницы от каталога языка, например reference/cli.md. * заменяет часть имени внутри одного каталога, ** — любое число каталогов, ? — один символ. |
rules[].profile |
Профиль для подошедших страниц. |
audiences |
Список читателей сайта, например ["reader", "author"]. Сейчас только проверяется на формат и на результат не влияет. |
Если странице подходят два правила с разными профилями, проверка
остановится с AUTHORING_RULE_CONFLICT. Уточните пути, чтобы у каждой
страницы был один профиль.
Профиль в front matter
Профиль одной страницы можно задать прямо в ней. Он важнее правил из
docara.authoring.json:
---
profile: how_to
---
# Как опубликовать сайт
Профили и что они проверяют
| Профиль | Для чего | Что должно быть на странице |
|---|---|---|
landing |
Вход в раздел и призыв к действию | Один заголовок #, вступление, не меньше двух разделов ##, ссылка или блок |
article |
Связный рассказ об одной теме | Один заголовок #, вступление, хотя бы один раздел ## |
tutorial |
Обучение на примере от начала до результата | Один заголовок #, нумерованный список хотя бы из двух шагов |
how_to |
Решение одной практической задачи | Один заголовок #, нумерованный список хотя бы из двух шагов |
reference |
Точные сведения для поиска | Один заголовок #, вступление, таблица, список, код или блок |
explanation |
Причины, устройство и ограничения | Один заголовок #, вступление, хотя бы один раздел ## |
Если части не хватает, docara validate page сообщает код
PAGE_PROFILE_<ЧАСТЬ>_MISSING, например PAGE_PROFILE_ORDERED_STEPS_MISSING.
Каждая проверенная страница также получает PAGE_EDITORIAL_REVIEW_REQUIRED —
список смысловых вопросов для редактора, на которые программа не отвечает.
php vendor/bin/docara validate page /ru/start/ --json
После docara build сборка печатает, сколько страниц требуют внимания, но
сайт всё равно собирается.
Ошибки файла
| Код | Причина и что сделать |
|---|---|
AUTHORING_JSON_INVALID |
Файл не является корректным JSON. Что сделать: Исправьте синтаксис. |
AUTHORING_SCHEMA_INVALID |
В файле не объект. Что сделать: Начните файл с {"schema": "docara.authoring.v1", ...}. |
SCHEMA_VALIDATION_FAILED |
Неизвестное поле, неверный профиль или путь в match с / в начале или ... Что сделать: Сверьте файл с таблицей выше. |
AUTHORING_FILE_UNSAFE |
Файл — символическая или жёсткая ссылка. Что сделать: Замените его обычным файлом. |
AUTHORING_RULE_CONFLICT |
Странице подходят правила с разными профилями. Что сделать: Уточните пути в match. |
AUTHORING_PROFILE_UNKNOWN |
Неизвестный профиль. Что сделать: Используйте один из шести профилей. |