Μετάβαση στο περιεχόμενο

Ξεκινώντας

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο 7b38e05

Αυτός ο οδηγός στήνει έναν ιστότοπο τεκμηρίωσης με το Onedocs από έναν κενό φάκελο. Αν έχετε ήδη έργο Next.js, παραλείψτε τα αρχεία που έχετε και συγκρίνετε τα υπόλοιπα.

Προαπαιτούμενα

  • Node.js 20.9 ή νεότερο (απαιτείται από το Next.js 16)
  • Next.js 16 με App Router, React 19.2 ή νεότερο
  • Tailwind CSS v4 (η προκαθορισμένη ρύθμιση Onedocs CSS εισάγει το tailwindcss)

Το Fumadocs UI 16 υποστηρίζει μόνο τα Next.js 16 και React 19.2, επομένως παλαιότερες εκδόσεις των Next.js ή React δεν λειτουργούν, παρόλο που τα μεταδεδομένα του πακέτου onedocs εξακολουθούν να τις αναφέρουν (#5).

Εγκατάσταση

Το Onedocs δεν περιλαμβάνει τα Next.js ή Fumadocs. Είναι εξαρτήσεις peer, οπότε τις εγκαθιστάτε δίπλα του:

Κέλυφος
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

Διατηρήστε την καρφίτσα lucide-react@0.562. Το onedocs 0.1.27 δηλώνει το lucide-react ^0.562.0 ως peer και, χωρίς την καρφίτσα, το npm εγκαθιστά το lucide-react 1.x και σταματά με σφάλμα ERESOLVE (#1).

Τα ίδια πακέτα λειτουργούν με pnpm, yarn ή bun.

Προσθέστε τα σενάρια Next.js στο package.json:

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

Δομή έργου

Αυτή είναι η δομή που θα έχετε στο τέλος:

Κώδικας
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

Ας δημιουργήσουμε κάθε αρχείο.

Αρχεία διαμόρφωσης

onedocs.config.ts

Το κύριο αρχείο διαμόρφωσης. Απαιτείται μόνο το title· για τα υπόλοιπα, δείτε την ενότητα Διαμόρφωση.

TypeScript
import { defineConfig } from "onedocs/config";

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

source.config.ts

Υποδεικνύει στο Fumadocs MDX πού βρίσκεται το περιεχόμενό σας. Αυτό είναι το μόνο σημείο όπου ορίζεται ο φάκελος περιεχομένου:

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

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

next.config.mjs

Ενεργοποιεί την επεξεργασία MDX:

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

const withMDX = createMDX();

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

export default withMDX(config);

Το Fumadocs MDX δημιουργεί φάκελο .source/ από το source.config.ts όταν ξεκινά το Next.js. Προσθέστε το .source στο .gitignore.

postcss.config.mjs

Εκτελεί το Tailwind CSS v4, πάνω στο οποίο βασίζεται η προκαθορισμένη ρύθμιση Onedocs CSS:

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

tsconfig.json

Τα παρακάτω παραδείγματα εισάγουν από το @/, επομένως αντιστοιχίστε το στο src/:

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

Το Next.js προσθέτει σε αυτό το αρχείο τις υπόλοιπες επιλογές μεταγλωττιστή που χρειάζεται, την πρώτη φορά που εκτελείτε το next dev ή το next build.

Ρύθμιση πηγής

src/lib/source.ts

Φορτώνει το περιεχόμενο της τεκμηρίωσής σας:

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

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

Αρχεία εφαρμογής

src/app/layout.tsx

Η διάταξη της ρίζας σας:

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 από το Fumadocs UI παρέχει το παράθυρο αναζήτησης και το φωτεινό και σκοτεινό θέμα. Το FontHead προφορτώνει τη γραμματοσειρά Inter Variable από το /fonts/InterVariable.woff2 και την ορίζει ως γραμματοσειρά σελίδας. Το Onedocs δεν περιλαμβάνει το αρχείο γραμματοσειράς: κατεβάστε το InterVariable.woff2 από τις εκδόσεις Inter και τοποθετήστε το στο public/fonts/. Χωρίς αυτό, το κείμενο χρησιμοποιεί την προεπιλεγμένη γραμματοσειρά sans-serif του συστήματος.

Για να δημιουργήσετε αυτά τα μεταδεδομένα από τις ρυθμίσεις σας, δείτε το createMetadata στην API Reference.

src/app/globals.css

Εισαγάγετε την προκαθορισμένη ρύθμιση CSS:

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

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

Η προκαθορισμένη ρύθμιση φορτώνει το Tailwind CSS, τα στυλ Fumadocs UI και τα στυλ διάταξης Onedocs. Οι διαδρομές @source είναι σχετικές με το globals.css, επομένως αυτές οι δύο γραμμές δείχνουν στο src/app/ και στον φάκελο content/ στη ρίζα του έργου.

src/app/page.tsx

Η αρχική σελίδα. Το HomePage αποδίδει το hero, τα χαρακτηριστικά και το υποσέλιδο από τη διαμόρφωσή σας:

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

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

Το packageName προσθέτει στο hero εντολές εγκατάστασης για τα npm, yarn, pnpm και bun. Παραλείψτε το αν το έργο σας δεν είναι πακέτο.

src/app/docs/layout.tsx

Διάταξη τεκμηρίωσης με πλευρική γραμμή:

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

Μεμονωμένες σελίδες τεκμηρίωσης:

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

Περιεχόμενο

content/docs/index.mdx

Κάθε σελίδα χρειάζεται ένα title στο frontmatter της. Το description είναι προαιρετικό:

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

Ορίζει τη σειρά της πλευρικής γραμμής:

JSON
{
  "pages": ["index"]
}

Προσθέστε μια σελίδα δημιουργώντας ένα ακόμη αρχείο .mdx και καταχωρίζοντας το όνομά του στο pages.

Εκτέλεση

Εκκινήστε τον διακομιστή ανάπτυξης:

Κέλυφος
npm run dev

Η αρχική σελίδα βρίσκεται στη διεύθυνση http://localhost:3000 και η τεκμηρίωση στη διεύθυνση http://localhost:3000/docs.

Δημιουργία για παραγωγή:

Κέλυφος
npm run build

Στη συνέχεια, προσθέστε αναζήτηση, χάρτη ιστοτόπου και llms.txt στην ενότητα SEO & Αναζήτηση.