Карта сайта: sitemap.yml

Один файл config/sitemap.yml задаёт структуру сайта. Это явное дерево: каждая строка задаёт страницу, а вложенность строк определяет иерархию адресов. Один файл — единственное место, где заданы адреса, заголовки, метаданные страниц и навигация.

Почему так, а не привычный file-as-route, объясняет решение о карте сайта.

Формат строки

Файл с расширением .yml читает собственный парсер отступов; полный синтаксис YAML не поддерживается. Используйте два пробела на уровень и строки списка без внешних кавычек. Заголовок sitemap: занимает отдельную строку; допустимы пустая форма sitemap: [] и комментарий после заголовка, но не декларация страницы. Значения известных полей layout и navLabel должны быть строками. Кавычки в значениях метаданных допустимы. Неверная запись страницы или неразбираемые метаданные завершают сборку с ошибкой; строка не пропускается молча.

Заголовок [адрес, файл.md, { layout: "имя" }]

Заголовок — текст до скобок. Движок включает его в данные карты сайта; зарегистрированный обработчик документа получает это значение, а стандартное расширение root использует его для <title>.
адрес — последний сегмент URL страницы. Абсолютный (с ведущим /) движок использует целиком, относительный добавляет к адресу родителя.
файл.md — путь к файлу контента относительно корня контента: первого уровня в levels.json (по умолчанию content/). Корнем может быть локальный каталог или клон внешнего репозитория.
{ layout: "имя" } — необязательные метаданные страницы. Движок сохраняет значение в page.layout и передаёт его зарегистрированному обработчику документа. Обработчик может использовать его при выборе шаблона; движок сам шаблон не выбирает и не предоставляет шаблон page по умолчанию.

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

Вложенность определяет адреса

Глубина отступа задаёт иерархию. Пример из реального сайта документации:

sitemap:
  - Главная [/, index.md]
  - Как строить [how, how/index.md]
    - С чего начать [start, how/start.md]
    - Модель данных [bemjson, how/bemjson.md]

Главная → /
Как строить → /how
С чего начать → /how/start (относительный start присоединился к родительскому /how)
Модель данных → /how/bemjson

Дерево каталогов и дерево адресов независимы: расположение .md не влияет на URL — итоговый адрес определяется только картой сайта.

Хлебные крошки и навигация

Из дерева sitemap.yml движок строит адреса, хлебные крошки и структуру меню — задавать их вручную не нужно. Отдельного файла навигации нет.

Метаданные шаблона

Необязательные метаданные шаблона задают в строке sitemap, а не в начале файла контента:

- Главная [/, index.md, { layout: "landing" }]
- Документация [docs, docs/index.md]

Здесь page.layout получает значение landing; оно влияет на HTML только если зарегистрированный обработчик документа читает это поле. Стандартный обработчик nuckty-ext-block-root оборачивает каждую страницу в root и не выбирает шаблон по page.layout. Подробнее об обработчиках документов и блоках — блоки и шаблоны nu.

Перекрёстные ссылки

Авторы пишут обычные ссылки в Markdown на файлы .md:

См. [модель данных](how/bemjson.md).

Движок преобразует путь в адрес по карте md2url, построенной из sitemap. Автору не нужно знать итоговый адрес — достаточно сослаться на файл. Подробнее — в разделе Markdown.

Когда карта сайта не подходит

Для сайтов с динамическим или пользовательским контентом, где страницы появляются без центральной регистрации, явное дерево неудобно. nuckty для этого не предназначен: карта сайта рассчитана на курируемую документацию с заранее известной структурой.