Alustamine

Vaata Markdownina Muuda teenuses GitHub Dokumentatsioon: 7b38e05

See juhend aitab seadistada tühjast kaustast dokumentatsioonisaidi, kasutades Onedocs. Kui sul on juba Next.js projekt, jäta olemasolevad failid vahele ja võrdle ülejäänuid.

Eeltingimused

Node.js 20.9 või uuem (nõutav versioonile Next.js 16)
Next.js 16 App Routeriga, React 19.2 või uuem
Tailwind CSS v4 (eelseadistus Onedocs CSS impordib tailwindcss)

Fumadocs UI 16 toetab ainult Next.js 16 ja React 19.2, seega vanemad Next.js või React versioonid ei tööta, kuigi paketi onedocs metaandmetes on need endiselt loetletud (#5).

Paigaldamine

Onedocs ei sisalda komplektis Next.js ega Fumadocs. Need on partner-sõltuvused, seega paigalda need selle kõrvale:

Shell

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

Jätke lucide-react@0.562 pin alles. onedocs 0.1.27 määrab lucide-react ^0.562.0-i partneriks ning ilma pin-ita installib npm lucide-react 1.x ja katkestab töö ERESOLVE veaga (#1).

Samad paketid töötavad ka pnpm-i, yarn-i ja bun-iga.

Lisa skriptid Next.js faili package.json:

JSON

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Projekti struktuur

Lõpptulemus näeb välja selline:

Kood

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

Loome nüüd kõik failid.

Konfiguratsioonifailid

onedocs.config.ts

Sinu peamine konfiguratsioonifail. Nõutav on ainult title; ülejäänu kohta vaata Konfigureerimine.

TypeScript

import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project",
  nav: {
    github: "username/repo",
  },
});

source.config.ts

Annab Fumadocs MDX-ile teada, kus sinu sisu asub. See on ainus koht, kus sisukausta asukoht määratakse:

TypeScript

import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
});

next.config.mjs

Lubab MDX töötlemise:

JavaScript

import { createMDX } from "fumadocs-mdx/next";

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {};

export default withMDX(config);

Fumadocs MDX loob source.config.ts põhjal .source/ kausta, kui Next.js käivitub. Lisage .source faili .gitignore.

postcss.config.mjs

Käivitab Tailwind CSS v4, millele põhineb eelseadistus Onedocs CSS:

JavaScript

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

tsconfig.json

Allolevad näited impordivad moodulist @/, seega suuna see asukohta src/:

JSON

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Next.js lisab sellesse faili esimesel käivitamisel ülejäänud vajalikud kompilaatori valikud, kui käivitad next dev või next build.

Lähtekoodi seadistus

src/lib/source.ts

Laadib dokumentatsiooni sisu:

TypeScript

import { loader } from "fumadocs-core/source";
import { docs } from "../../.source/server";

export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});

Rakenduse failid

src/app/layout.tsx

Sinu juurpaigutus:

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 (
    <html lang="en" suppressHydrationWarning>
      <head>
        <FontHead />
      </head>
      <body className="antialiased">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

Moodul RootProvider paketist Fumadocs UI pakub otsingudialoogi ning heledat ja tumedat kujundust. FontHead laadib Inter Variable'i fondi ette asukohast /fonts/InterVariable.woff2 ja määrab selle lehe fondiks. Onedocs ei sisalda fondifaili: laadi InterVariable.woff2 alla Interi väljalasetest ja paiguta see asukohta public/fonts/. Ilma selleta kasutatakse süsteemi sans-serif-fonti.

Selle metaandmestiku loomiseks oma konfiguratsiooni põhjal vaata createMetadata jaotises API viide.

src/app/globals.css

Impordi eelseadistus CSS:

CSS

@import "onedocs/css/preset.css";

@source "./**/*.tsx";
@source "../../content/**/*.mdx";

Eelseadistus laadib Tailwind CSS, Fumadocs UI stiilid ja Onedocs paigutusstiilid. @source teed on suhtelised asukoha globals.css suhtes, seega viitavad need kaks rida asukohale src/app/ ja projekti juurkaustas olevale kaustale content/.

src/app/page.tsx

Avaleht. HomePage renderdab konfiguratsiooni põhjal avavaate, funktsioonid ja jaluse:

TSX

import { HomePage } from "onedocs";
import config from "../../onedocs.config";

export default function Home() {
  return <HomePage config={config} packageName="my-package" />;
}

packageName lisab avavaatele paigalduskäsud pakettidele npm, yarn, pnpm ja bun. Jäta see välja, kui sinu projekt pole pakett.

src/app/docs/layout.tsx

Dokumentatsiooni paigutus külgribaga:

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 (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}

src/app/docs/[[...slug]]/page.tsx

Üksikud dokumentatsioonilehed:

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 (
    <DocsPage toc={page.data.toc}>
      <MDX components={mdxComponents} />
    </DocsPage>
  );
}

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,
  };
}

Sisu

content/docs/index.mdx

Iga lehe esiosas peavad olema title. description on valikuline:

Mdx

---
title: Introduction
description: What this project does.
---

Welcome to the docs. Components such as `<Callout>` work without imports; see [Components](/docs/components).

content/docs/meta.json

Määrab külgriba järjestuse:

JSON

{
  "pages": ["index"]
}

Lisa leht, luues veel ühe faili .mdx ja loetledes selle nime failis pages.

Käivitamine

Käivita arendusserver:

Shell

npm run dev

Avaleht asub aadressil http://localhost:3000 ja dokumentatsioon aadressil http://localhost:3000/docs.

Loo tootmisversioon:

Shell

npm run build

Seejärel lisa otsing, saidikaart ja llms.txt jaotises SEO ja otsing.