Слои конфигурации
Какой файл править для какой задачи — от названия портала до палитры и маршрутов.
Настройки шаблона разделены по слоям: чем выше слой, тем чаще его правят при развертывании нового портала.
Слой 1 — портал
lib/portal.config.ts — единственный файл, обязательный к правке при
развертывании нового портала.
| Поле | Влияет на |
|---|---|
name, shortName | Навбар, шаблон <title>, Open Graph-изображения. |
tagline, description | Hero-блок главной страницы и meta description. |
docsRoute | Базовый путь документации, content negotiation в proxy.ts. |
git.user, git.repo, git.branch | Ссылка на репозиторий в навбаре и кнопка «View on GitHub» на каждой странице. |
products[] | Карточки продуктов на главной странице. |
externalPortals[] | Пункты навигации и карточки связанных порталов. |
placeholders | Тексты и целевые адреса страниц /swagger и /flows. |
Синхронизация с содержимым
products[] описывает карточки на главной странице, а выпадающий список
строится из каталогов с "root": true. Это два независимых источника —
добавляя продукт, обновите оба: каталог в content/docs/ и запись в конфиге.
Слой 2 — бренд
| Файл | Содержит |
|---|---|
lib/brand.ts | Палитра, градиент, пути к ассетам и названия шрифтов как TypeScript-константы. Используется в React (Open Graph, инлайновые стили). |
app/global.css | Те же значения как CSS-переменные плюс переопределение палитры Fumadocs (--color-fd-*) для светлой и темной темы. |
app/layout.tsx | Подключение шрифтов через next/font/google. |
public/brand/ | Логотипы и паттерны из брендбука. |
Подробности — в разделе Бренд и стили.
Слой 3 — структура документации
content/docs/**/meta.json и frontmatter .mdx-файлов. Код не затрагивается:
добавление продукта, раздела или страницы — операция над содержимым.
Слой 4 — конвейер сборки
Правится редко, при изменении самого шаблона.
| Файл | Когда править |
|---|---|
source.config.ts | Расширение схем frontmatter, добавление remark/rehype-плагинов. |
next.config.mjs | Редиректы, заголовки, режим сборки. |
proxy.ts | Правила content negotiation. |
components/mdx.tsx | Регистрация новых компонентов, доступных в MDX. |
lib/layout.shared.tsx | Изменение состава верхней навигации. |
app/docs/layout.tsx | Поведение бокового меню и выпадающего списка продуктов. |
Переменные окружения
Значения, зависящие от среды развертывания, а не от кода.
| Переменная | Назначение |
|---|---|
NEXT_PUBLIC_SITE_URL | Базовый адрес портала для metadataBase и абсолютных Open Graph-ссылок. |
PORT | Порт HTTP-сервера. |
HOSTNAME | Интерфейс прослушивания; в контейнере 0.0.0.0. |