# Referência de API

Referência completa de todas as exportações do pacote `onedocs`.

## Pontos de entrada

| Importação | Descrição |
|--------|-------------|
| `onedocs` | Entrada principal: layouts, componentes, `mdxComponents`, `defineConfig`, auxiliares de origem |
| `onedocs/components` | Componentes Fumadocs UI, além de `InstallBlock`, `CodeBlock`, `Button` e `Logo` |
| `onedocs/config` | Auxiliares de configuração |
| `onedocs/source` | Utilitários de origem de conteúdo |
| `onedocs/metadata` | Geração de metadados |
| `onedocs/og` | Geração de imagens OpenGraph |
| `onedocs/llms` | Geração de LLMs.txt |
| `onedocs/seo` | Sitemap e robots.txt |
| `onedocs/css/preset.css` | Predefinição Tailwind CSS |

## Layouts

### DocsLayout

Componente de layout principal para páginas de documentação. Fornece navegação lateral, pesquisa e alternância de tema.

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

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

**Propriedades:**
- `config` - Seu objeto `OnedocsConfig`
- `pageTree` - Árvore de páginas da sua origem (e.g., `source.pageTree`)
- `children` - Conteúdo da página

### DocsPage

Invólucro para páginas individuais de documentação. Envolve Fumadocs UI `DocsPage` e coloca o conteúdo em `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>
  );
}
```

**Propriedades:**
- `toc` - Sumário da página
- `children` - Conteúdo MDX
- Qualquer outra propriedade de Fumadocs UI `DocsPage`, como `full`

### DocsBody

Invólucro interno do corpo do conteúdo da documentação. Usado internamente por `DocsPage`.

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

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

### HomePage

Componente completo da página inicial, com seção principal, recursos e rodapé.

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

**Propriedades:**
- `config` - Seu objeto `OnedocsConfig`
- `packageName` - Nome do pacote para o bloco de instalação (opcional)
- `children` - Conteúdo entre os recursos e o rodapé (opcional)

Consulte a [página inicial](https://onedocs.inline0.dev/pt/docs/configuration#homepage) e o [rodapé](https://onedocs.inline0.dev/pt/docs/configuration#footer) para saber o que a configuração controla.

### HomeLayout

Layout base da página inicial (usado internamente por `HomePage`).

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

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

### createBaseOptions

Cria as opções de layout Fumadocs UI (título ou logotipo da barra de navegação, `nav.links` e link GitHub) com base na sua configuração. `DocsLayout` e `HomeLayout` usam esse recurso; chame-o você mesmo ao renderizar diretamente um layout Fumadocs UI.

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

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

## Componentes

### InstallBlock

Abas de gerenciadores de pacotes que mostram comandos de instalação para npm, yarn, pnpm e bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). É um componente assíncrono de servidor.

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

<InstallBlock packageName="onedocs" />
```

**Propriedades:**
- `packageName` - O nome do pacote npm a instalar
- `title` - Título acima das abas (opcional)
- `description` - Texto acima das abas (opcional)
- `children` - Conteúdo abaixo das abas (opcional)

### Button

Link arredondado com estilo de botão primário. Há um único estilo.

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

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

**Propriedades:**
- `href` - Destino do link
- `children` - Texto do botão
- `className` - Classes adicionais (opcional)

### Logo

Renderiza uma imagem clara e outra escura e exibe a que corresponde ao tema atual. `DocsLayout` e `HomePage` usam esse recurso para um `logo` com variantes clara e escura.

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

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

**Propriedades:**
- `light` - Caminho da imagem para o modo claro
- `dark` - Caminho da imagem para o modo escuro
- `alt` - Texto alternativo (padrão: `"Logo"`)
- `className` - Classes para ambas as imagens (opcional)

### CTASection

Seção de chamada para ação da página inicial.

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

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

**Propriedades:**
- `title` - Título da seção
- `description` - Texto abaixo do título (opcional)
- `cta` - Configuração do botão com `label` e `href`
- `children` - Conteúdo abaixo do botão (opcional)

### FontHead

Pré-carrega a fonte Inter Variable, declara seu `@font-face` e a define como fonte da página. Adicione ao `<head>` do layout raiz.

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

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

Onedocs não inclui a fonte. Por padrão, `FontHead` carrega `/fonts/InterVariable.woff2`, então coloque o arquivo em `public/fonts/` ou passe outro URL com `fontPath`:

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

### GitHubIcon

Componente de ícone GitHub (usado internamente na navegação).

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

<GitHubIcon className="size-5" />
```

### CodeBlock

Bloco de código com realce de sintaxe, realçado no servidor com Shiki por meio de Fumadocs. É um componente assíncrono de servidor.

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

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

## Configuração

### defineConfig

Auxiliar de configuração com segurança de tipos.

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

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

### OnedocsConfig

Tipo TypeScript para configuração.

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

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

Consulte [Configuração](https://onedocs.inline0.dev/pt/docs/configuration) para ver todas as opções.

## Utilitários de origem

### loader

Reexportação do carregador `fumadocs-core/source` para criar origens de conteúdo.

```tsx
import { loader } from "onedocs/source";

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

### createSource

Auxiliar para criar uma origem de conteúdo (invólucro em torno do carregador). A origem URL base usa `/docs` como padrão.

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

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

Em 0.1.27, `createSource` retorna uma origem sem tipagem, então TypeScript relata erros como `Property 'data' does not exist on type 'unknown'` ao ler `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Use `loader` como mostrado acima até que isso seja corrigido.

## Metadados

### createMetadata

Gera metadados Next.js para o layout raiz.

```tsx
import { createMetadata } from "onedocs/metadata";

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

**Opções:**
- `baseUrl` - URL base do seu site (opcional)
- `additional` - Campos `Metadata` adicionais, mesclados por último (opcional)

**Retorna:** objeto de metadados Next.js `Metadata` com:
- Título (`config.title`) e modelo de título (`%s | Site Name`)
- Descrição
- Ícone do site de `config.icon`, quando definido
- Quando `baseUrl` estiver definido: `metadataBase`, metadados OpenGraph e cartão Twitter `summary_large_image`

### createDocsPageMetadata

Gera os metadados de título e descrição para uma página de documentação. Recebe um objeto com `title` e um `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 uma imagem Open Graph específica da página, consulte [Imagens OG dinâmicas](#dynamic-og-images).

## Imagens OpenGraph

### createRootOGImage

Cria uma imagem OG para a página inicial: seu logotipo centralizado em um fundo preto.

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

Cria uma imagem OG para páginas de documentação: o logotipo no canto superior esquerdo e o título em branco sobre fundo preto. O argumento de fonte é opcional; sem ele, o título usa a fonte do 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);
}
```

### Imagens OG dinâmicas

Para imagens OG específicas de cada página, disponibilize-as em uma rota. As páginas não apontam automaticamente para essa rota: adicione-a manualmente aos metadados de cada página, por exemplo com `openGraph: { images: "/docs/og/getting-started" }` junto aos 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);
}
```

### Funções auxiliares

| Função | Descrição |
|----------|-------------|
| `loadPublicFile(path)` | Carrega um arquivo de `public/` como dados URL e buffer; para arquivos SVG, também lê os atributos `width` e `height` |
| `loadInterFont(path?)` | Carrega uma fonte de `public/` para imagens OG, `fonts/Inter-Medium.ttf` por padrão |
| `ogImageSize` | Dimensões padrão de imagem OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Tipo MIME `"image/png"` |

**Arquivos necessários:**
- `public/logo-dark.svg` - Logotipo para imagens OG. Os auxiliares OG dimensionam-no com base nos atributos `width` e `height`, então a tag `<svg>` precisa conter ambos como números simples.
- `public/fonts/Inter-Medium.ttf` - Fonte para títulos. Onedocs não a inclui.

## LLMs.txt

Gera arquivos LLMs.txt para assistentes de IA.

### generateLLMsText

Gera conteúdo LLMs.txt conciso. Recebe uma origem envolvida por `createLLMsSource` e `{ title, description? }` e retorna uma promessa.

```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" },
  });
}
```

Os URLs das páginas são registrados conforme vêm da origem, por exemplo `/docs/getting-started`, sem domínio.

### generateLLMsFullText

Gera LLMs.txt completo com todo o conteúdo das páginas. Recebe apenas a origem envolvida e retorna uma promessa.

```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" },
  });
}
```

Os corpos das páginas são incluídos somente quando `includeProcessedMarkdown` de Fumadocs MDX está ativado; consulte [SEO e Pesquisa](https://onedocs.inline0.dev/pt/docs/seo-search#full-content-version).

### createLLMsSource

Envolve uma origem Fumadocs (resultado de `loader()` ou `createSource()`) no formato lido pelas duas funções acima: o URL, o título, a descrição e os carregadores de texto de cada página.

## SEO

### generateSitemap

Gera um sitemap para sua documentação. Recebe um objeto: `baseUrl`, a lista `pages` (geralmente de `meta.json`) e um `docsPath` opcional (padrão `/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 ?? [],
  });
}
```

Consulte [SEO e Pesquisa](https://onedocs.inline0.dev/pt/docs/seo-search#sitemap) para saber como as entradas se tornam URLs.

### generateRobots

Gera conteúdo robots.txt: permite tudo, além das linhas `Host` e `Sitemap`. `sitemapPath` usa `/sitemap.xml` como padrão.

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

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

## Predefinição CSS

Importe a predefinição CSS no seu `globals.css`:

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

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

Os caminhos `@source` são relativos a `src/app/globals.css`.

A predefinição inclui:
- Tailwind CSS v4 (instale `tailwindcss` e `@tailwindcss/postcss` por conta própria)
- Tema neutro Fumadocs
- Estilos da predefinição Fumadocs
- `--font-sans` definido para a variável `--font-inter` definida por `FontHead`
- Recursos OpenType do Inter para texto corrido e títulos
- Estilos de layout de altura total e ajustes de layout Onedocs

## Componentes MDX

A exportação `mdxComponents` espalha os componentes padrão Fumadocs UI MDX e adiciona os componentes abaixo:

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

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

**Componentes incluídos:**
- Padrões Fumadocs UI: `pre` (blocos de código), `a`, `img`, `h1` a `h6` (títulos com âncoras), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` - Destaques informativos, de aviso e de erro
- `Card`, `Cards` - Layouts de cartões
- `Tab`, `Tabs` - Conteúdo com abas
- `Step`, `Steps` - Etapas numeradas
- `Accordion`, `Accordions` - Seções recolhíveis
- `File`, `Folder`, `Files` - Árvores de arquivos
- `ImageZoom` - Imagens com zoom
- `TypeTable` - Tabelas de documentação de tipos

`InstallBlock` e `CodeBlock` não estão incluídos; adicione-os você mesmo conforme mostrado em [Componentes](https://onedocs.inline0.dev/pt/docs/components#more-components).

Consulte [Componentes](https://onedocs.inline0.dev/pt/docs/components) para ver exemplos de uso.