Kezdő lépések

Megtekintés Markdownként Szerkesztés itt: GitHub Dokumentáció itt: 7b38e05

Ez az útmutató egy üres mappából állít be dokumentációs webhelyet a Onedocs segítségével. Ha már van Next.js projektje, hagyja ki a meglévő fájlokat, és tekintse át a többit.

Előfeltételek

Node.js 20.9 vagy újabb (a Next.js 16 ezt igényli)
Next.js 16 App Routerrel, React 19.2 vagy újabb
Tailwind CSS v4 (az Onedocs CSS előbeállítás importálja a tailwindcss csomagot)

A Fumadocs UI 16 csak a Next.js 16-ot és a React 19.2-t támogatja, ezért a régebbi Next.js- vagy React-verziók nem működnek, noha a onedocs csomag metaadatai továbbra is felsorolják őket (#5).

Telepítés

A Onedocs nem tartalmazza a Next.js és a Fumadocs csomagot. Ezek társfüggőségek, ezért mellette kell telepíteni őket:

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

Hagyja meg a lucide-react@0.562 verziórögzítést. A onedocs 0.1.27 társfüggőségként deklarálja a lucide-react ^0.562.0 csomagot, és verziórögzítés nélkül a npm telepíti a lucide-react 1.x verzióját, majd ERESOLVE hibával leáll (#1).

Ugyanezek a csomagok pnpm, yarn vagy bun használatával is működnek.

Adja hozzá a Next.js szkripteket a package.json fájlhoz:

JSON

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

A projekt felépítése

A végeredmény így fog kinézni:

Kód

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

Hozzuk létre egyenként a fájlokat.

Konfigurációs fájlok

onedocs.config.ts

Ez a fő konfigurációs fájl. Csak a title szükséges; a többihez lásd a Konfiguráció részt.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Megadja, hogy a Fumadocs MDX hol találja a tartalmat. A tartalommappát csak itt kell beállítani:

TypeScript

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

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

next.config.mjs

Engedélyezi a MDX feldolgozást:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX indításkor source.config.ts alapján .source/ mappát hoz létre. Adja hozzá: Next.js .source .gitignore.

postcss.config.mjs

Futtatja a Tailwind CSS v4 parancsot, amelyre az Onedocs CSS előbeállítás épül:

JavaScript

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

tsconfig.json

Az alábbi példák a @/ modulból importálnak, ezért rendelje hozzá a src/ útvonalat:

JSON

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

A Next.js az első next dev vagy next build futtatásakor hozzáadja ehhez a fájlhoz a szükséges további fordítóbeállításokat.

A forrás beállítása

src/lib/source.ts

Betölti a dokumentáció tartalmát:

TypeScript

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

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

Alkalmazásfájlok

src/app/layout.tsx

A gyökérelrendezés:

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

A Fumadocs UI csomagból származó RootProvider biztosítja a keresőablakot és a világos, illetve sötét témát. A FontHead előtölti az Inter Variable betűtípust a /fonts/InterVariable.woff2 helyről, és beállítja az oldal betűtípusaként. A Onedocs nem tartalmazza a betűtípusfájlt: töltse le a InterVariable.woff2 fájlt az Inter kiadások oldalról, és helyezze el a public/fonts/ mappában. Enélkül a szöveg a rendszer sans-serif betűtípusával jelenik meg.

Ha inkább a konfigurációból építené fel ezeket a metaadatokat, lásd a createMetadata részt az API dokumentációs referenciában.

src/app/globals.css

Importálja a CSS előbeállítást:

CSS

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

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

Az előbeállítás betölti a Tailwind CSS csomagot, az Fumadocs UI stílusait és az Onedocs elrendezésstílusait. A @source útvonalak a globals.css-hez viszonyítottak, így ez a két sor a src/app/ fájlra és a projekt gyökerében található content/ mappára mutat.

src/app/page.tsx

A kezdőlap. A HomePage a konfigurációból jeleníti meg a kiemelt részt, a funkciókat és a láblécet:

TSX

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

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

A packageName telepítési parancsokat ad hozzá a npm, yarn, pnpm és bun számára. Hagyja ki, ha a projektje nem csomag.

src/app/docs/layout.tsx

Dokumentációs elrendezés oldalsávval:

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

Az egyes dokumentációs oldalak:

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

Tartalom

content/docs/index.mdx

Minden oldalhoz szükség van egy title mezőre az előfejlécben. A description nem kötelező:

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

Beállítja az oldalsáv sorrendjét:

JSON

{
  "pages": ["index"]
}

Új oldal létrehozásához hozzon létre egy másik .mdx fájlt, és sorolja fel a nevét a pages fájlban.

Futtatás

Indítsa el a fejlesztői szervert:

Shell

npm run dev

A kezdőlap a http://localhost:3000, a dokumentáció pedig a http://localhost:3000/docs útvonalon érhető el.

Készítsen éles kiadásra szánt buildet:

Shell

npm run build

Ezután adja hozzá a keresést, a webhelytérképet és a llms.txt funkciót a SEO és keresés útmutató alapján.