Začetek

Prikaži kot Markdown Uredi na GitHub Dokumentacija za 7b38e05

Ta vodič vas vodi skozi nastavitev spletnega mesta z dokumentacijo in Onedocs v prazni mapi. Če že imate projekt Next.js, preskočite datoteke, ki jih že imate, in primerjajte preostale.

Predpogoji

Node.js 20.9 ali novejši (zahteva ga Next.js 16)
Next.js 16 z App Router, React 19.2 ali novejši
Tailwind CSS v4 (prednastavitev Onedocs CSS uvozi tailwindcss)

Fumadocs UI 16 podpira samo Next.js 16 in React 19.2, zato starejše različice Next.js ali React ne delujejo, čeprav jih metapodatki paketa onedocs še vedno navajajo (#5).

Namestitev

Onedocs ne vključuje Next.js ali Fumadocs. Gre za odvisnosti vrstnikov, zato ju namestite poleg njega:

Lupina

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

Ohranite pripeto različico lucide-react@0.562. onedocs 0.1.27 navaja lucide-react ^0.562.0 kot odvisnost vrstnika; če različica ni pripeta, npm namesti lucide-react 1.x in se ustavi z napako ERESOLVE (#1).

Isti paketi delujejo tudi s pnpm, yarn ali bun.

Skripte Next.js dodajte v package.json:

JSON

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

Struktura projekta

Končni rezultat bo videti takole:

Koda

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

Ustvarimo vsako datoteko.

Konfiguracijske datoteke

onedocs.config.ts

Vaša glavna konfiguracijska datoteka. Obvezna je samo title; za preostale možnosti glejte Konfiguracija.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Funkciji Fumadocs MDX pove, kje je vaša vsebina. To je edino mesto, kjer nastavite mapo z vsebino:

TypeScript

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

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

next.config.mjs

Omogoči obdelavo MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX ob zagonu Next.js ustvari mapo .source/ iz source.config.ts. Dodajte .source v .gitignore.

postcss.config.mjs

Zažene Tailwind CSS v4, na katerem temelji prednastavitev Onedocs CSS:

JavaScript

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

tsconfig.json

Spodnji primeri uvažajo iz @/, zato ga preslikajte v src/:

JSON

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

Next.js ob prvem zagonu next dev ali next build tej datoteki doda preostale potrebne možnosti prevajalnika.

Nastavitev vira

src/lib/source.ts

Naloži vsebino vaše dokumentacije:

TypeScript

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

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

Datoteke aplikacije

src/app/layout.tsx

Vaša korenska postavitev:

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 iz Fumadocs UI ponuja pogovorno okno za iskanje ter svetlo in temno temo. FontHead vnaprej naloži pisavo Inter Variable iz /fonts/InterVariable.woff2 in jo nastavi kot pisavo strani. Onedocs ne vključuje datoteke pisave: prenesite InterVariable.woff2 iz izdaj Inter in jo shranite v public/fonts/. Brez nje se uporabi sistemska pisava sans-serif.

Če želite te metapodatke namesto tega sestaviti iz konfiguracije, glejte createMetadata v APIReferenci.

src/app/globals.css

Uvozite prednastavitev CSS:

CSS

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

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

Prednastavitev naloži Tailwind CSS, sloge Fumadocs UI in sloge postavitve Onedocs. Poti @source so relativne glede na globals.css, zato ti dve vrstici kažeta na src/app/ in mapo content/ v korenski mapi projekta.

src/app/page.tsx

Domača stran. HomePage iz konfiguracije izriše uvodni del, funkcije in nogo:

TSX

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

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

packageName v uvodni del doda ukaze za namestitev za npm, yarn, pnpm in bun. Izpustite ga, če vaš projekt ni paket.

src/app/docs/layout.tsx

Postavitev dokumentacije s stransko vrstico:

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

Posamezne strani dokumentacije:

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

Vsebina

content/docs/index.mdx

Vsaka stran mora imeti title v sprednji vsebini. description je izbiren:

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

Določi vrstni red stranske vrstice:

JSON

{
  "pages": ["index"]
}

Stran dodate tako, da ustvarite še eno datoteko .mdx in navedete njeno ime v pages.

Zagon

Zaženite razvojni strežnik:

Lupina

npm run dev

Domača stran je na naslovu http://localhost:3000, dokumentacija pa na http://localhost:3000/docs.

Ustvarite produkcijsko različico:

Lupina

npm run build

Nato dodajte iskanje, zemljevid mesta in llms.txt v razdelku SEO in iskanje.