Конвейер сборки

Путь от .mdx-файла до отрендеренной страницы, поиска и машиночитаемых представлений.

fumadocs-mdx читает source.config.ts, обходит content/docs/, валидирует frontmatter и meta.json по Zod-схемам и создает каталог .source/ с типизированной коллекцией и виртуальным модулем collections/server.

Запускается скриптом postinstall, а также первым шагом pnpm types:check.

Загрузчик

lib/source.ts вызывает loader() из fumadocs-core/source: строит дерево страниц, назначает базовый URL /docs и подключает плагин иконок.

lib/source.ts

export const source = loader({
  baseUrl: docsRoute,
  source: docs.toFumadocsSource(),
  plugins: [lucideIconsPlugin()],
});

Рендеринг

app/docs/[[...slug]]/page.tsx получает страницу по slug, рендерит её тело через getMDXComponents() и собирает оглавление, кнопки Markdown и GitHub, Open Graph-метаданные.

generateStaticParams() перечисляет все страницы, поэтому документация предрендерится на этапе сборки.

Обработка MDX

source.config.ts описывает коллекцию и remark-плагины:

source.config.ts

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    schema: pageSchema,
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
  meta: {
    schema: metaSchema,
  },
});

export default defineConfig({
  mdxOptions: {
    remarkPlugins: [remarkMdxMermaid],
  },
});

includeProcessedMarkdown сохраняет обработанный Markdown каждой страницы — на нем построены /llms.txt, /llms-full.txt и кнопка «Copy Markdown»;
remarkMdxMermaid превращает блоки ```mermaid в компонент <Mermaid />, зарегистрированный в components/mdx.tsx.

Диаграммы Mermaid

components/mdx/mermaid.tsx — клиентский компонент. Библиотека mermaid загружается динамически и кешируется по паре «текст диаграммы + тема», тема диаграммы синхронизирована со темой портала через next-themes.

Дополнительные представления

Маршрут	Что отдает
`/api/search`	Индекс полнотекстового поиска Fumadocs.
`/llms.txt`	Краткий индекс: заголовки, описания и URL всех страниц.
`/llms-full.txt`	Полный обработанный Markdown всех страниц одним файлом.
`/llms.mdx/docs/<путь>/content.md`	Markdown отдельной страницы.
`/og/docs/<путь>/image.png`	Open Graph-изображение в брендовых цветах.

Content negotiation

proxy.ts перехватывает запросы к документации и отдает Markdown вместо HTML, если клиент явно его просит:

суффикс .md в адресе — /docs/doc-portal/architecture.md;
заголовок Accept, в котором Markdown приоритетнее HTML (типично для LLM-агентов и CLI-клиентов).

Оба случая переписываются на /llms.mdx/docs/<путь>/content.md без редиректа.

Продукционная сборка

next.config.mjs включает output: 'standalone' — Next.js собирает самодостаточный server.js вместе с минимальным набором зависимостей. Dockerfile копирует именно этот результат, поэтому образ не содержит node_modules целиком.

Этапы

Генерация коллекции