# Първи стъпки Това ръководство настройва сайт за документация с 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. Те са peer зависимости, затова ги инсталирайте заедно с него: ```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` като peer зависимост, а без фиксираната версия 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/bg/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 генерира папка `.source/` от `source.config.ts` при стартиране на Next.js. Добавете `.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/`. Без него текстът използва системния sans-serif шрифт. За да генерирате тези метаданни от конфигурацията си, вижте `createMetadata` в [справочника за API](https://onedocs.inline0.dev/bg/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/bg/docs/seo-search).