Primeros pasos

Ver como Markdown Editar en GitHub Documentación de 7b38e05

Esta guía configura un sitio de documentación con Onedocs desde una carpeta vacía. Si ya tienes un proyecto Next.js, omite los archivos que ya tengas y compara los demás.

Requisitos previos

Node.js 20.9 o posterior (requerido por Next.js 16)
Next.js 16 con App Router, React 19.2 o posterior
Tailwind CSS v4 (el ajuste preestablecido Onedocs CSS importa tailwindcss)

Fumadocs UI 16 solo admite Next.js 16 y React 19.2, así que las versiones anteriores de Next.js o React no funcionan, aunque los metadatos del paquete onedocs todavía las indiquen (#5).

Instalación

Onedocs no incluye Next.js ni Fumadocs. Son dependencias de pares, así que debes instalarlas junto con él:

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

Mantén fijada la versión de lucide-react@0.562. onedocs 0.1.27 declara lucide-react ^0.562.0 como dependencia de pares; sin la versión fijada, npm instala lucide-react 1.x y se detiene con un error ERESOLVE (#1).

Los mismos paquetes funcionan con pnpm, yarn o bun.

Añade los scripts Next.js a package.json:

JSON

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

Estructura del proyecto

Esto es lo que tendrás al terminar:

Código

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

Vamos a crear cada archivo.

Archivos de configuración

onedocs.config.ts

Tu archivo de configuración principal. Solo se requiere title; consulta Configuración para el resto.

TypeScript

import { defineConfig } from "onedocs/config";

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

source.config.ts

Indica a Fumadocs MDX dónde está el contenido. Este es el único lugar donde se define la carpeta de contenido:

TypeScript

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

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

next.config.mjs

Activa el procesamiento de MDX:

JavaScript

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

const withMDX = createMDX();

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

export default withMDX(config);

Fumadocs MDX genera una carpeta .source/ a partir de source.config.ts cuando se inicia Next.js. Añade .source a .gitignore.

postcss.config.mjs

Ejecuta Tailwind CSS v4, en el que se basa el ajuste preestablecido de Onedocs CSS:

JavaScript

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

tsconfig.json

Los ejemplos siguientes importan desde @/, así que configúralo como src/:

JSON

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

Next.js añade a este archivo las opciones restantes del compilador que necesita la primera vez que ejecutas next dev o next build.

Configuración de la fuente

src/lib/source.ts

Carga el contenido de tu documentación:

TypeScript

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

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

Archivos de la aplicación

src/app/layout.tsx

Diseño raíz:

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 de Fumadocs UI proporciona el diálogo de búsqueda y los temas claro y oscuro. FontHead precarga la fuente Inter Variable de /fonts/InterVariable.woff2 y la establece como fuente de la página. Onedocs no incluye el archivo de la fuente: descarga InterVariable.woff2 desde las versiones de Inter y colócalo en public/fonts/. Sin ella, el texto usa la fuente sans serif del sistema.

Para generar estos metadatos a partir de tu configuración, consulta createMetadata en la referencia de API.

src/app/globals.css

Importa el ajuste preestablecido de CSS:

CSS

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

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

El ajuste preestablecido carga Tailwind CSS, los estilos Fumadocs UI y los estilos de diseño Onedocs. Las rutas de @source son relativas a globals.css; por tanto, estas dos líneas apuntan a src/app/ y a la carpeta content/ en la raíz del proyecto.

src/app/page.tsx

La página de inicio. HomePage muestra el contenido destacado, las funciones y el pie de página de tu configuración:

TSX

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

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

packageName añade al contenido destacado comandos de instalación para npm, yarn, pnpm y bun. Omítelo si tu proyecto no es un paquete.

src/app/docs/layout.tsx

Diseño de documentación con barra lateral:

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

Páginas de documentación individuales:

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

Contenido

content/docs/index.mdx

Cada página necesita un title en su materia inicial. El description es opcional:

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

Define el orden de la barra lateral:

JSON

{
  "pages": ["index"]
}

Añade una página creando otro archivo .mdx e indicando su nombre en pages.

Ejecución

Inicia el servidor de desarrollo:

Shell

npm run dev

La página de inicio está en http://localhost:3000 y la documentación en http://localhost:3000/docs.

Compila para producción:

Shell

npm run build

A continuación, añade la búsqueda, un mapa del sitio y llms.txt en SEO y búsqueda.