# Початок роботи У цьому посібнику описано, як із порожньої папки налаштувати сайт документації з Onedocs. Якщо у вас уже є проєкт Next.js, пропустіть файли, які вже маєте, і звірте решту. ## Необхідні умови - Node.js 20.9 або новіша версія (потрібна для Next.js 16) - Next.js 16 з App Router, React 19.2 або новіша версія - Tailwind CSS v4 (пресет Onedocs CSS імпортує `tailwindcss`) Fumadocs UI 16 підтримує лише Next.js 16 і React 19.2, тому старіші версії Next.js або React не працюють, хоча в метаданих пакета `onedocs` вони досі зазначені ([#5](https://github.com/inline0/onedocs/issues/5)). ## Встановлення Onedocs не містить Next.js або Fumadocs. Це залежності однорангового рівня, тож їх потрібно встановити поруч із ним: ```bash npm install onedocs fumadocs-core fumadocs-mdx fumadocs-ui lucide-react@0.562 next react react-dom npm install -D tailwindcss @tailwindcss/postcss typescript @types/react @types/react-dom @types/node ``` Залиште фіксацію версії `lucide-react@0.562`. `onedocs` 0.1.27 оголошує `lucide-react` `^0.562.0` залежністю однорангового рівня, а без фіксації версії npm встановлює lucide-react 1.x і завершується з помилкою `ERESOLVE` ([#1](https://github.com/inline0/onedocs/issues/1)). Ті самі пакети працюють із pnpm, yarn або bun. Додайте скрипти Next.js до `package.json`: ```json title="package.json" { "scripts": { "dev": "next dev", "build": "next build", "start": "next start" } } ``` ## Структура проєкту Ось що ви отримаєте: ``` your-project/ ├── content/ │ └── docs/ │ ├── index.mdx │ └── meta.json ├── public/ │ └── fonts/ │ └── InterVariable.woff2 ├── src/ │ ├── app/ │ │ ├── layout.tsx │ │ ├── page.tsx │ │ ├── globals.css │ │ └── docs/ │ │ ├── layout.tsx │ │ └── [[...slug]]/ │ │ └── page.tsx │ └── lib/ │ └── source.ts ├── onedocs.config.ts ├── source.config.ts ├── next.config.mjs ├── postcss.config.mjs ├── tsconfig.json └── package.json ``` Створімо кожен файл. ## Файли конфігурації ### onedocs.config.ts Ваш основний файл конфігурації. Обов’язковий лише `title`; решту див. у розділі [Конфігурація](https://onedocs.inline0.dev/uk/docs/configuration). ```ts title="onedocs.config.ts" import { defineConfig } from "onedocs/config"; export default defineConfig({ title: "My Docs", description: "Documentation for my project", nav: { github: "username/repo", }, }); ``` ### source.config.ts Вказує Fumadocs MDX, де міститься ваш вміст. Це єдине місце, де задається папка вмісту: ```ts title="source.config.ts" import { defineDocs } from "fumadocs-mdx/config"; export const docs = defineDocs({ dir: "content/docs", }); ``` ### next.config.mjs Вмикає обробку MDX: ```js title="next.config.mjs" import { createMDX } from "fumadocs-mdx/next"; const withMDX = createMDX(); /** @type {import('next').NextConfig} */ const config = {}; export default withMDX(config); ``` Fumadocs MDX під час запуску Next.js створює папку `.source/` на основі `source.config.ts`. Додайте `.source` до `.gitignore`. ### postcss.config.mjs Запускає Tailwind CSS v4, на основі якого створено пресет Onedocs CSS: ```js title="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; ``` ### tsconfig.json У наведених нижче прикладах імпорт виконується з `@/`, тож зіставте його з `src/`: ```json title="tsconfig.json" { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } } ``` Next.js під час першого запуску `next dev` або `next build` додає до цього файлу решту потрібних параметрів компілятора. ## Налаштування джерела ### src/lib/source.ts Завантажує вміст документації: ```ts title="src/lib/source.ts" import { loader } from "fumadocs-core/source"; import { docs } from "../../.source/server"; export const source = loader({ baseUrl: "/docs", source: docs.toFumadocsSource(), }); ``` ## Файли застосунку ### src/app/layout.tsx Кореневий макет: ```tsx title="src/app/layout.tsx" import type { Metadata } from "next"; import { RootProvider } from "fumadocs-ui/provider/next"; import { FontHead } from "onedocs"; import "./globals.css"; export const metadata: Metadata = { title: "My Docs", description: "Documentation for my project", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` `RootProvider` з Fumadocs UI надає діалог пошуку та світлу й темну теми. `FontHead` попередньо завантажує шрифт Inter Variable з `/fonts/InterVariable.woff2` і призначає його шрифтом сторінки. Onedocs не містить файлу шрифту: завантажте `InterVariable.woff2` зі сторінки [релізів Inter](https://github.com/rsms/inter/releases) і помістіть його в `public/fonts/`. Без нього текст відображатиметься системним шрифтом без зарубок. Щоб натомість створити ці метадані з конфігурації, див. `createMetadata` у довіднику [API Reference](https://onedocs.inline0.dev/uk/docs/api-reference#createmetadata). ### src/app/globals.css Імпортуйте пресет CSS: ```css title="src/app/globals.css" @import "onedocs/css/preset.css"; @source "./**/*.tsx"; @source "../../content/**/*.mdx"; ``` Пресет завантажує Tailwind CSS, стилі Fumadocs UI і стилі макета Onedocs. Шляхи `@source` відносні до `globals.css`, тож ці два рядки вказують на `src/app/` і папку `content/` в корені проєкту. ### src/app/page.tsx Домашня сторінка. `HomePage` відображає головний блок, переваги й нижній колонтитул із вашої конфігурації: ```tsx title="src/app/page.tsx" import { HomePage } from "onedocs"; import config from "../../onedocs.config"; export default function Home() { return ; } ``` `packageName` додає до головного блоку команди встановлення для npm, yarn, pnpm і bun. Не додавайте його, якщо ваш проєкт не є пакетом. ### src/app/docs/layout.tsx Макет документації з бічною панеллю: ```tsx title="src/app/docs/layout.tsx" import { DocsLayout } from "onedocs"; import type { ReactNode } from "react"; import { source } from "@/lib/source"; import config from "../../../onedocs.config"; export default function Layout({ children }: { children: ReactNode }) { return ( {children} ); } ``` ### src/app/docs/[[...slug]]/page.tsx Окремі сторінки документації: ```tsx title="src/app/docs/[[...slug]]/page.tsx" import { source } from "@/lib/source"; import { DocsPage, mdxComponents } from "onedocs"; import { notFound } from "next/navigation"; export default async function Page(props: { params: Promise<{ slug?: string[] }>; }) { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); const MDX = page.data.body; return ( ); } export async function generateStaticParams() { return source.generateParams(); } export async function generateMetadata(props: { params: Promise<{ slug?: string[] }>; }) { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); return { title: page.data.title, description: page.data.description, }; } ``` ## Вміст ### content/docs/index.mdx У frontmatter кожної сторінки має бути `title`. `description` необов’язковий: ```mdx title="content/docs/index.mdx" --- title: Introduction description: What this project does. --- Welcome to the docs. Components such as `` work without imports; see [Components](/docs/components). ``` ### content/docs/meta.json Визначає порядок елементів бічної панелі: ```json title="content/docs/meta.json" { "pages": ["index"] } ``` Щоб додати сторінку, створіть ще один файл `.mdx` і вкажіть його назву в `pages`. ## Запуск Запустіть сервер розробки: ```bash npm run dev ``` Домашня сторінка доступна за адресою `http://localhost:3000`, а документація — за адресою `http://localhost:3000/docs`. Зберіть версію для продакшену: ```bash npm run build ``` Далі додайте пошук, карту сайту й llms.txt у розділі [SEO і пошук](https://onedocs.inline0.dev/uk/docs/seo-search).