Kom godt i gang

Vis som Markdown Rediger på GitHub Dokumentation hos 7b38e05

Denne vejledning opsætter et dokumentationswebsted med Onedocs fra en tom mappe. Hvis du allerede har et Next.js-projekt, kan du springe de filer over, du har, og sammenligne resten.

Forudsætninger

Node.js 20.9 eller nyere (kræves af Next.js 16)
Next.js 16 med App Router, React 19.2 eller nyere
Tailwind CSS v4 (forudindstillingen Onedocs CSS importerer tailwindcss)

Fumadocs UI 16 understøtter kun Next.js 16 og React 19.2, så ældre versioner af Next.js eller React virker ikke, selvom pakkens metadata for onedocs stadig angiver dem (#5).

Installation

Onedocs inkluderer ikke Next.js eller Fumadocs. De er peer-afhængigheder, så du installerer dem ved siden af:

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

Behold lucide-react@0.562-fastlåsningen. onedocs 0.1.27 angiver lucide-react ^0.562.0 som en peer-afhængighed, og uden fastlåsningen installerer npm lucide-react 1.x og stopper med en ERESOLVE-fejl (#1).

De samme pakker fungerer med pnpm, yarn eller bun.

Tilføj scripts Next.js til package.json:

JSON

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

Projektstruktur

Sådan ser resultatet ud:

Kode

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

Lad os oprette hver fil.

Konfigurationsfiler

onedocs.config.ts

Din primære konfigurationsfil. Kun title er påkrævet; se Konfiguration for resten.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Fortæller Fumadocs MDX, hvor dit indhold ligger. Dette er det eneste sted, hvor indholdsmappen angives:

TypeScript

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

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

next.config.mjs

Aktiverer behandling af MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX genererer en mappe .source/ fra source.config.ts, når Next.js starter. Tilføj .source til .gitignore.

postcss.config.mjs

Kører Tailwind CSS v4, som forudindstillingen Onedocs CSS er bygget på:

JavaScript

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

tsconfig.json

Eksemplerne nedenfor importerer fra @/, så tilknyt det til src/:

JSON

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

Next.js føjer de resterende compilerindstillinger til denne fil, første gang du kører next dev eller next build.

Kildeopsætning

src/lib/source.ts

Indlæser dit dokumentationsindhold:

TypeScript

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

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

Appfiler

src/app/layout.tsx

Dit rodlayout:

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 fra Fumadocs UI leverer søgedialogen samt det lyse og mørke tema. FontHead forudindlæser Inter Variable-skrifttypen fra /fonts/InterVariable.woff2 og angiver den som sidens skrifttype. Onedocs leverer ikke skrifttypefilen: download InterVariable.woff2 fra Inter-udgivelser, og læg den i public/fonts/. Uden den bruger teksten systemets sans-serif-skrifttype.

Hvis du vil opbygge disse metadata ud fra din konfiguration i stedet, kan du se createMetadata i API-referencen.

src/app/globals.css

Importér forudindstillingen CSS:

CSS

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

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

Forudindstillingen indlæser Tailwind CSS, typografierne Fumadocs UI og layouttypografierne Onedocs. Stierne @source er relative til globals.css, så disse to linjer peger på src/app/ og på mappen content/ i projektets rod.

src/app/page.tsx

Startsiden. HomePage gengiver hero-sektionen, funktionerne og sidefoden fra din konfiguration:

TSX

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

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

packageName føjer installationskommandoer til npm, yarn, pnpm og bun til hero-sektionen. Udelad den, hvis dit projekt ikke er en pakke.

src/app/docs/layout.tsx

Dokumentationslayout med sidepanel:

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

Individuelle dokumentationssider:

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

Indhold

content/docs/index.mdx

Hver side skal have en title i sine frontmatter-data. description er valgfri:

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

Angiver rækkefølgen i sidepanelet:

JSON

{
  "pages": ["index"]
}

Tilføj en side ved at oprette en anden fil af typen .mdx og angive dens navn i pages.

Kør det

Start udviklingsserveren:

Shell

npm run dev

Startsiden findes på http://localhost:3000 og dokumentationen på http://localhost:3000/docs.

Byg til produktion:

Shell

npm run build

Tilføj derefter søgning, et sitemap og llms.txt i SEO og søgning.