Darbo pradžia

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: 7b38e05

Šiame vadove nuo tuščio aplanko nustatoma dokumentacijos svetainė su Onedocs. Jei jau turite Next.js projektą, praleiskite jau sukurtus failus ir palyginkite likusius.

Būtinosios sąlygos

Node.js 20.9 arba naujesnė versija (reikalinga Next.js 16)
Next.js 16 su App Router, React 19.2 arba naujesnė versija
Tailwind CSS v4 (Onedocs CSS išankstinis nustatymas importuoja tailwindcss)

Fumadocs UI 16 palaiko tik Next.js 16 ir React 19.2, todėl senesnės Next.js arba React versijos neveikia, nors paketo onedocs metaduomenyse jos vis dar nurodytos (#5).

Diegimas

Onedocs neapima Next.js ar Fumadocs. Tai bendrai naudojamos priklausomybės, todėl įdiekite jas greta:

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

Palikite prisegtą lucide-react@0.562 versiją. onedocs 0.1.27 nurodo lucide-react ^0.562.0 kaip bendrą priklausomybę, o be prisegtos versijos npm įdiegia lucide-react 1.x ir sustoja su ERESOLVE klaida (#1).

Tie patys paketai veikia su pnpm, yarn arba bun.

Pridėkite Next.js scenarijus į package.json:

JSON

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

Projekto struktūra

Štai ką turėsite pabaigę:

Kodas

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

Sukurkime kiekvieną failą.

Konfigūracijos failai

onedocs.config.ts

Pagrindinis konfigūracijos failas. Privalomas tik title; apie kitus skaitykite skiltyje Konfigūracija.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Nurodo Fumadocs MDX, kur yra jūsų turinys. Tai vienintelė vieta, kurioje nustatomas turinio aplankas:

TypeScript

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

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

next.config.mjs

Įgalina MDX apdorojimą:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX paleidžiant Next.js iš source.config.ts sukuria aplanką .source/. Pridėkite .source prie .gitignore.

postcss.config.mjs

Paleidžia Tailwind CSS v4, kuriuo pagrįstas išankstinis nustatymas Onedocs CSS:

JavaScript

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

tsconfig.json

Toliau pateiktuose pavyzdžiuose importuojama iš @/, todėl susiekite jį su src/:

JSON

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

Next.js pirmą kartą paleidus next dev arba next build prie šio failo prideda likusias reikalingas kompiliatoriaus parinktis.

Šaltinio sąranka

src/lib/source.ts

Įkelia dokumentacijos turinį:

TypeScript

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

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

Programos failai

src/app/layout.tsx

Jūsų šakninis išdėstymas:

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

Fumadocs UI esantis RootProvider pateikia paieškos dialogo langą, šviesią ir tamsią temas. FontHead iš anksto įkelia Inter Variable šriftą iš /fonts/InterVariable.woff2 ir nustato jį kaip puslapio šriftą. Onedocs šrifto failo netiekia: atsisiųskite InterVariable.woff2 iš Inter leidimų ir įdėkite į public/fonts/. Jei jo nėra, tekstui naudojamas atsarginis sistemos sans-serif šriftas.

Kaip vietoj to generuoti šiuos metaduomenis iš konfigūracijos, žr. createMetadata skiltyje API nuoroda.

src/app/globals.css

Importuokite CSS išankstinį nustatymą:

CSS

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

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

Išankstinis nustatymas įkelia Tailwind CSS, Fumadocs UI stilius ir Onedocs išdėstymo stilius. @source keliai nurodomi globals.css atžvilgiu, todėl šios dvi eilutės nurodo src/app/ ir projekto šakniniame aplanke esantį aplanką content/.

src/app/page.tsx

Pradžios puslapis. HomePage iš jūsų konfigūracijos atvaizduoja pagrindinę sritį, funkcijas ir poraštę:

TSX

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

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

packageName pagrindinėje srityje prideda npm, yarn, pnpm ir bun diegimo komandas. Praleiskite, jei jūsų projektas nėra paketas.

src/app/docs/layout.tsx

Dokumentacijos išdėstymas su šonine juosta:

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

Atskiri dokumentacijos puslapiai:

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

Turinys

content/docs/index.mdx

Kiekvieno puslapio metaduomenyse būtinas title. description yra pasirinktinis:

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

Nustato šoninės juostos tvarką:

JSON

{
  "pages": ["index"]
}

Pridėkite puslapį sukurdami kitą .mdx failą ir įrašydami jo pavadinimą į pages.

Paleidimas

Paleiskite kūrimo serverį:

Shell

npm run dev

Pradžios puslapis yra http://localhost:3000, o dokumentacija – http://localhost:3000/docs.

Sukurkite gamybinę versiją:

Shell

npm run build

Tada skiltyje SEO ir paieška pridėkite paiešką, svetainės žemėlapį ir llms.txt.