Модель контента

Продукты, разделы и страницы — как структура каталогов превращается в навигацию и URL.

Три уровня иерархии

Продукт

Каталог первого уровня внутри content/docs/, в meta.json которого указано "root": true.

content/docs/doc-portal/meta.json

{
  "title": "Doc-Portal",
  "description": "Шаблон портала документации Reactive Engineering",
  "icon": "BookMarked",
  "root": true,
  "pages": ["index", "getting-started", "architecture", "how-to", "brand-and-styles"]
}

Признак root заставляет Fumadocs выделить каталог в отдельный корень дерева страниц. Layout документации получает такие корни как «tabs» и при tabMode="auto" рисует их выпадающим списком над боковым меню. title, description и icon формируют содержимое пункта списка.

Один продукт — один пункт дропдауна

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

Раздел

Вложенный каталог без root. Его meta.json задает название, иконку и порядок страниц:

content/docs/doc-portal/architecture/meta.json

{
  "title": "Архитектура",
  "description": "Модель контента, конвейер сборки и слои конфигурации",
  "icon": "Waypoints",
  "pages": ["index", "content-model", "build-pipeline", "configuration-layers"]
}

Страница

Файл .mdx с frontmatter:

---
title: Модель контента
description: Продукты, разделы и страницы.
icon: Layers
---

Содержимое страницы...

Поле	Обязательное	Назначение
`title`	да	Заголовок страницы, пункт бокового меню, `<title>` документа.
`description`	нет	Подзаголовок на странице, `meta description`, описание в поиске.
`icon`	нет	Имя иконки Lucide, отображается в боковом меню.
`full`	нет	`true` — страница на всю ширину, без области оглавления.

Формирование URL

URL собирается из пути файла относительно content/docs/, база — /docs.

Файл	URL
`content/docs/index.mdx`	`/docs`
`content/docs/doc-portal/index.mdx`	`/docs/doc-portal`
`content/docs/doc-portal/architecture/index.mdx`	`/docs/doc-portal/architecture`
`content/docs/doc-portal/architecture/content-model.mdx`	`/docs/doc-portal/architecture/content-model`

index.mdx представляет корень своего каталога. Имя каталога попадает в публичный адрес, поэтому названия каталогов задаются латиницей в kebab-case.

Правила поля `pages`

Массив pages перечисляет элементы явно и определяет их порядок в боковом меню.

{
  "pages": ["index", "installation", "project-structure"]
}

элементы указываются без расширения .mdx;
каталоги указываются по имени каталога;
"..." добавляет все неперечисленные элементы в конец;
"---Название---" вставляет разделитель между группами;
элемент, не указанный в pages и без "...", не попадает в навигацию, хотя страница остается доступной по прямому URL.

Типичная ошибка

Файл создан, но не добавлен в pages — страница «пропадает» из бокового меню. Всегда перечисляйте страницы явно.

Иконки

Значение icon разрешается плагином lucideIconsPlugin в lib/source.ts по карте имен библиотеки lucide-react. Имя указывается в PascalCase: Rocket, Waypoints, BookMarked, Terminal, Palette.

Неизвестное имя не ломает сборку — плагин выводит предупреждение [lucide-icons-plugin] Unknown icon detected и не рисует иконку.