# Referencia de API

Referencia completa de todas las exportaciones del paquete `onedocs`.

## Puntos de entrada

| Importación | Descripción |
|--------|-------------|
| `onedocs` | Entrada principal: diseños, componentes, `mdxComponents`, `defineConfig`, utilidades de origen |
| `onedocs/components` | Componentes Fumadocs UI más `InstallBlock`, `CodeBlock`, `Button` y `Logo` |
| `onedocs/config` | Ayudantes de configuración |
| `onedocs/source` | Utilidades de origen del contenido |
| `onedocs/metadata` | Generación de metadatos |
| `onedocs/og` | Generación de imágenes OpenGraph |
| `onedocs/llms` | Generación de LLMs.txt |
| `onedocs/seo` | Mapa del sitio y robots.txt |
| `onedocs/css/preset.css` | Preajuste de Tailwind CSS |

## 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.

```tsx
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`.

```tsx
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`.

```tsx
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.

```tsx
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](https://onedocs.inline0.dev/es/docs/configuration#homepage) y [pie de página](https://onedocs.inline0.dev/es/docs/configuration#footer) para ver qué controla la configuración.

### HomeLayout

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

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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`:

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

### GitHubIcon

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

```tsx
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.

```tsx
import { CodeBlock } from "onedocs";

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

## Configuración

### defineConfig

Ayudante de configuración con seguridad de tipos.

```tsx
import { defineConfig } from "onedocs/config";

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

### OnedocsConfig

Tipo TypeScript para la configuración.

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

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

Consulte [Configuración](https://onedocs.inline0.dev/es/docs/configuration) para ver todas las opciones.

## Utilidades de origen

### loader

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

```tsx
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.

```tsx
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](https://github.com/inline0/onedocs/issues/4)). Use `loader` como se muestra arriba hasta que se solucione.

## Metadatos

### createMetadata

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

```tsx
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.

```tsx
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](#dynamic-og-images).

## Imágenes OpenGraph

### createRootOGImage

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

```tsx
// 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.

```tsx
// 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`.

```tsx
// 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

| Función | Descripción |
|----------|-------------|
| `loadPublicFile(path)` | Carga un archivo de `public/` como datos URL y búfer; para los SVG también lee los atributos `width` y `height` |
| `loadInterFont(path?)` | Carga una fuente de `public/` para las imágenes OG; de forma predeterminada, `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Dimensiones estándar de imagen OG: `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Tipo MIME estándar `"image/png"` |

**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.

```tsx
// 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.

```tsx
// 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](https://onedocs.inline0.dev/es/docs/seo-search#full-content-version).

### 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`).

```tsx
// 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](https://onedocs.inline0.dev/es/docs/seo-search#sitemap) 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`.

```tsx
// 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`:

```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:

```tsx
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](https://onedocs.inline0.dev/es/docs/components#more-components).

Consulta [Componentes](https://onedocs.inline0.dev/es/docs/components) para ver ejemplos de uso.