Darba sākšana

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 7b38e05

Šajā pamācībā no tukšas mapes tiek izveidota dokumentācijas vietne ar Onedocs. Ja jums jau ir Next.js projekts, izlaidiet jau esošos failus un salīdziniet pārējos.

Priekšnosacījumi

Node.js 20.9 vai jaunāka versija (nepieciešama Next.js 16)
Next.js 16 ar App Router, React 19.2 vai jaunāka versija
Tailwind CSS v4 (Onedocs CSS sākotnējā konfigurācija importē tailwindcss)

Fumadocs UI 16 atbalsta tikai Next.js 16 un React 19.2, tāpēc vecākas Next.js vai React versijas nedarbojas, lai gan pakotnes onedocs metadatos tās joprojām ir norādītas (#5).

Instalēšana

Onedocs neietver Next.js vai Fumadocs. Tās ir vienādranga atkarības, tāpēc instalējiet tās blakus šai pakotnei:

Apvalks

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

Paturiet piesprausto lucide-react@0.562 versiju. onedocs 0.1.27 deklarē lucide-react ^0.562.0 kā vienādranga atkarību, un bez piespraustās versijas npm instalē lucide-react 1.x un apstājas ar ERESOLVE kļūdu (#1).

Tās pašas pakotnes darbojas ar pnpm, yarn vai bun.

Pievienojiet Next.js skriptus failā package.json:

JSON

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

Projekta struktūra

Lūk, kāda būs projekta struktūra:

Kods

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

Izveidosim katru failu.

Konfigurācijas faili

onedocs.config.ts

Galvenais konfigurācijas fails. Obligāts ir tikai title; pārējo skatiet sadaļā Konfigurācija.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Norāda Fumadocs MDX, kur atrodas saturs. Šī ir vienīgā vieta, kur tiek iestatīta satura mape:

TypeScript

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

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

next.config.mjs

Iespējo MDX apstrādi:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX ģenerē mapi .source/ no source.config.ts, kad tiek palaists Next.js. Pievienojiet .source pie .gitignore.

postcss.config.mjs

Palaiž Tailwind CSS v4, uz kura balstīta sākotnējā konfigurācija Onedocs CSS:

JavaScript

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

tsconfig.json

Tālākajos piemēros tiek importēts no @/, tāpēc piesaistiet to src/:

JSON

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

Pirmoreiz palaižot next dev vai next build, Next.js šim failam pievieno pārējās nepieciešamās kompilatora opcijas.

Avota iestatīšana

src/lib/source.ts

Ielādē dokumentācijas saturu:

TypeScript

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

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

Lietotnes faili

src/app/layout.tsx

Saknes izkārtojums:

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

RootProvider no Fumadocs UI nodrošina meklēšanas dialogu, kā arī gaišo un tumšo tēmu. FontHead ielādē Inter Variable fontu no /fonts/InterVariable.woff2 un iestata to kā lapas fontu. Onedocs nepiegādā fonta failu: lejupielādējiet InterVariable.woff2 no Inter laidumiem un ievietojiet to mapē public/fonts/. Bez tā tekstā tiek izmantots sistēmas sans-serif fonts.

Lai šos metadatus veidotu no konfigurācijas, skatiet sadaļu createMetadata, kas atrodas API uzziņu materiālā.

src/app/globals.css

Importējiet sākotnējo konfigurāciju CSS:

CSS

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

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

Sākotnējā konfigurācija ielādē Tailwind CSS, Fumadocs UI stilus un izkārtojuma Onedocs stilus. Ceļi @source ir attiecībā pret globals.css, tāpēc šīs divas rindas norāda uz src/app/ un uz projekta saknes mapes mapi content/.

src/app/page.tsx

Sākumlapa. HomePage no jūsu konfigurācijas renderē galveno bloku, iespējas un kājeni:

TSX

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

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

packageName galvenajam blokam pievieno instalēšanas komandas priekš npm, yarn, pnpm un bun. Izlaidiet to, ja jūsu projekts nav pakotne.

src/app/docs/layout.tsx

Dokumentācijas izkārtojums ar sānjoslu:

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

Atsevišķas dokumentācijas lapas:

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

Saturs

content/docs/index.mdx

Katras lapas frontmatter sadaļā jābūt norādītam title. description nav obligāts:

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

Nosaka sānjoslas secību:

JSON

{
  "pages": ["index"]
}

Pievienojiet lapu, izveidojot vēl vienu .mdx failu un norādot tā nosaukumu failā pages.

Palaišana

Palaidiet izstrādes serveri:

Apvalks

npm run dev

Sākumlapa ir pieejama adresē http://localhost:3000, bet dokumentācija — http://localhost:3000/docs.

Izveidojiet produkcijas versiju:

Apvalks

npm run build

Pēc tam pievienojiet meklēšanu, vietnes karti un llms.txt sadaļā SEO un meklēšana.