Referencia de API

Referencia completa de todas las exportaciones del paquete onedocs.

Puntos de entrada

Diseños

DocsLayout

Contenedor del diseño principal para páginas de documentación. Proporciona navegación lateral, búsqueda y un selector de tema.

import { DocsLayout } from "onedocs";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}

Props:

• config: su objeto OnedocsConfig
• pageTree: árbol de páginas de su fuente (e.g, source.pageTree)
• children: contenido de la página

DocsPage

Contenedor para páginas de documentación individuales. Envuelve Fumadocs UI DocsPage y coloca el contenido en DocsBody.

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

Props:

• toc: tabla de contenidos de los datos de la página
• children: contenido de MDX
• Cualquier otra propiedad de Fumadocs UI DocsPage, como full

DocsBody

Contenedor interno del cuerpo del contenido de documentación. Lo usa internamente DocsPage.

import { DocsBody } from "onedocs";

<DocsBody>
  <MDX components={mdxComponents} />
</DocsBody>

HomePage

Componente completo para la página de inicio, con sección principal, funciones y pie de página.

import { HomePage, CTASection } from "onedocs";

export default function Home() {
  return (
    <HomePage config={config} packageName="my-package">
      <CTASection
        title="Ready to get started?"
        cta={{ label: "Read the Docs", href: "/docs" }}
      />
    </HomePage>
  );
}

Props:

• config: su objeto OnedocsConfig
• packageName: nombre del paquete para el bloque de instalación (opcional)
• children: contenido entre las funciones y el pie de página (opcional)

Consulte página de inicio y pie de página para ver qué controla la configuración.

HomeLayout

Diseño base de la página de inicio (usado internamente por HomePage).

import { HomeLayout } from "onedocs";

<HomeLayout config={config}>
  {/* Custom homepage content */}
</HomeLayout>

createBaseOptions

Crea las opciones de diseño Fumadocs UI (título o logotipo de la barra de navegación, nav.links y el enlace GitHub) a partir de su configuración. DocsLayout y HomeLayout lo usan; llámelo usted mismo al renderizar directamente un diseño Fumadocs UI.

import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { createBaseOptions } from "onedocs";

<DocsLayout {...createBaseOptions(config)} tree={source.pageTree}>
  {children}
</DocsLayout>

Componentes

InstallBlock

Pestañas de gestores de paquetes con comandos de instalación para npm, yarn, pnpm y bun (npm i, yarn add, pnpm add, bun add). Es un componente de servidor asíncrono.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Props:

• packageName: nombre del paquete npm que se instalará
• title: encabezado sobre las pestañas (opcional)
• description: texto sobre las pestañas (opcional)
• children: contenido debajo de las pestañas (opcional)

Button

Enlace redondeado con estilo de botón principal. Tiene un único estilo.

import { Button } from "onedocs";

<Button href="/docs">Get Started</Button>

Props:

• href: destino del enlace
• children: texto del botón
• className: clases adicionales (opcional)

Logo

Muestra una imagen clara y otra oscura, y elige la que coincide con el tema actual. DocsLayout y HomePage lo usan para un logo con variantes claras y oscuras.

import { Logo } from "onedocs";

<Logo light="/logo-light.svg" dark="/logo-dark.svg" alt="My Project" className="h-6" />

Props:

• light: ruta de la imagen para el modo claro
• dark: ruta de la imagen para el modo oscuro
• alt: texto alternativo (predeterminado: "Logo")
• className: clases para ambas imágenes (opcional)

CTASection

Sección de llamada a la acción para la página de inicio.

import { CTASection } from "onedocs";

<CTASection
  title="Ready to get started?"
  description="Optional description text"
  cta={{ label: "Get Started", href: "/docs" }}
/>

Props:

• title: encabezado de la sección
• description: texto bajo el encabezado (opcional)
• cta: configuración del botón con label y href
• children: contenido debajo del botón (opcional)

FontHead

Precarga la fuente Inter Variable, declara su @font-face y la establece como fuente de la página. Añádala a <head> del diseño raíz.

import { FontHead } from "onedocs";

<html>
  <head>
    <FontHead />
  </head>
  <body>{children}</body>
</html>

Onedocs no incluye la fuente. De forma predeterminada, FontHead carga /fonts/InterVariable.woff2; coloque el archivo en public/fonts/ o pase otro URL con fontPath:

<FontHead fontPath="/assets/Inter.woff2" />

GitHubIcon

Componente de icono GitHub (usado internamente en la navegación).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Bloque de código con resaltado de sintaxis, resaltado en el servidor con Shiki mediante Fumadocs. Es un componente de servidor asíncrono.

import { CodeBlock } from "onedocs";

<CodeBlock lang="tsx" code="const x = 1;" />

Configuración

defineConfig

Ayudante de configuración con seguridad de tipos.

import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  // ... other options
});

OnedocsConfig

Tipo TypeScript para la configuración.

import type { OnedocsConfig } from "onedocs/config";

const config: OnedocsConfig = {
  title: "My Docs",
};

Consulte Configuración para ver todas las opciones.

Utilidades de origen

loader

Reexportación del cargador fumadocs-core/source para crear fuentes de contenido.

import { loader } from "onedocs/source";

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

createSource

Ayudante para crear una fuente de contenido (contenedor del cargador). La base URL tiene /docs como valor predeterminado.

import { createSource } from "onedocs/source";
import { docs } from "../../.source/server";

export const source = createSource(docs);
// export const source = createSource(docs, { baseUrl: "/guide" });

En 0.1.27, createSource devuelve una fuente sin tipado, por lo que TypeScript informa de errores como Property 'data' does not exist on type 'unknown' al leer page.data (#4). Use loader como se muestra arriba hasta que se solucione.

Metadatos

createMetadata

Genera metadatos Next.js para el diseño raíz.

import { createMetadata } from "onedocs/metadata";

export const metadata = createMetadata(config, {
  baseUrl: "https://example.com",
});

Opciones:

• baseUrl: URL base del sitio (opcional)
• additional: campos Metadata adicionales, combinados al final (opcional)

Devuelve: objeto Next.js Metadata con:

• Título (config.title) y plantilla de título (%s | Site Name)
• Descripción
• Favicon de config.icon, si se ha establecido
• Si se ha establecido baseUrl: metadataBase, metadatos OpenGraph y una tarjeta Twitter summary_large_image

createDocsPageMetadata

Genera los metadatos de título y descripción de una página de documentación. Recibe un objeto con title y un description opcional.

import { createDocsPageMetadata } from "onedocs/metadata";
import { notFound } from "next/navigation";

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return createDocsPageMetadata({
    title: page.data.title,
    description: page.data.description,
  });
}

Para una imagen Open Graph específica de cada página, consulta Imágenes OG dinámicas.

Imágenes OpenGraph

createRootOGImage

Crea una imagen OG para la página de inicio: tu logotipo centrado sobre un fondo negro.

// src/app/opengraph-image.tsx
import {
  createRootOGImage,
  loadPublicFile,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const logo = await loadPublicFile("logo-dark.svg");
  return createRootOGImage(logo as OGImageLogo);
}

createDocsOGImage

Crea una imagen OG para las páginas de documentación: el logotipo en la esquina superior izquierda y el título en blanco sobre negro. El argumento de fuente es opcional; si se omite, el título usa la fuente del sistema.

// src/app/docs/opengraph-image.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);
  return createDocsOGImage("Documentation", logo as OGImageLogo, font);
}

Imágenes OG dinámicas

Para usar imágenes OG específicas de cada página, sírvelas desde una ruta. Las páginas no apuntan automáticamente a esta ruta: añádela manualmente a los metadatos de cada página, por ejemplo con openGraph: { images: "/docs/og/getting-started" } junto a los campos de createDocsPageMetadata.

// src/app/docs/og/[...slug]/route.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  type OGImageLogo,
} from "onedocs/og";
import { source } from "@/lib/source";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug: string[] }> }
) {
  const { slug } = await params;
  const page = source.getPage(slug);
  const title = page?.data.title ?? "Documentation";

  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);

  return createDocsOGImage(title, logo as OGImageLogo, font);
}

Funciones auxiliares

Archivos necesarios:

• public/logo-dark.svg - Logotipo para las imágenes OG. Las funciones auxiliares OG ajustan su tamaño según los atributos width y height, por lo que la etiqueta <svg> debe incluir ambos como números sin comillas.
• public/fonts/Inter-Medium.ttf - Fuente para los títulos. Onedocs no la incluye.

LLMs.txt

Genera archivos LLMs.txt para asistentes de IA.

generateLLMsText

Genera contenido LLMs.txt conciso. Recibe una fuente delimitada por createLLMsSource y { title, description? }, y devuelve una promesa.

// src/app/llms.txt/route.ts
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsText(createLLMsSource(source), {
    title: "My Project",
    description: "Project description",
  });

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Las URL de las páginas se escriben tal como vienen de la fuente; por ejemplo, /docs/getting-started, sin dominio.

generateLLMsFullText

Genera LLMs.txt completo con todo el contenido de las páginas. Recibe únicamente la fuente delimitada y devuelve una promesa.

// src/app/llms-full.txt/route.ts
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsFullText(createLLMsSource(source));

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

Los cuerpos de las páginas solo se incluyen cuando está activada la opción Fumadocs MDX de includeProcessedMarkdown; consulta SEO y búsqueda.

createLLMsSource

Envuelve una fuente Fumadocs (resultado de loader() o createSource()) con la estructura que leen las dos funciones anteriores: los cargadores de URL, título, descripción y texto de cada página.

SEO

generateSitemap

Genera un mapa del sitio para tu documentación. Recibe un objeto: baseUrl, la lista de pages (normalmente de meta.json) y un docsPath opcional (valor predeterminado: /docs).

// src/app/sitemap.ts
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

export default function sitemap() {
  return generateSitemap({
    baseUrl: "https://example.com",
    pages: meta.pages ?? [],
  });
}

Consulta SEO y búsqueda para saber cómo las entradas se convierten en URL.

generateRobots

Genera contenido robots.txt: permite todo y añade las líneas Host y Sitemap. De forma predeterminada, sitemapPath es /sitemap.xml.

// src/app/robots.ts
import { generateRobots } from "onedocs/seo";

export default function robots() {
  return generateRobots({
    baseUrl: "https://example.com",
  });
}

Ajuste preestablecido de CSS

Importa el ajuste preestablecido de CSS en tu globals.css:

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

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

Las rutas de @source son relativas a src/app/globals.css.

El ajuste preestablecido incluye:

• Tailwind CSS v4 (instala tailwindcss y @tailwindcss/postcss por tu cuenta)
• Tema neutro de Fumadocs
• Estilos preestablecidos de Fumadocs
• --font-sans configurado con la variable --font-inter definida por FontHead
• Funciones OpenType de Inter para el texto del cuerpo y los encabezados
• Estilos de diseño a altura completa y ajustes de diseño de Onedocs

Componentes de MDX

La exportación de mdxComponents extiende los componentes predeterminados Fumadocs UI MDX y añade los componentes siguientes:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Componentes incluidos:

• Valores predeterminados de Fumadocs UI: pre (bloques de código), a, img, h1 a h6 (encabezados con anclas), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Avisos informativos, de advertencia y de error
• Card, Cards - Diseños de tarjetas
• Tab, Tabs - Contenido con pestañas
• Step, Steps - Pasos numerados
• Accordion, Accordions - Secciones plegables
• File, Folder, Files - Árboles de archivos
• ImageZoom - Imágenes con zoom
• TypeTable - Tablas de documentación de tipos

InstallBlock y CodeBlock no están incluidos; añádelos como se muestra en Componentes.

Consulta Componentes para ver ejemplos de uso.