Referência de API

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

Pontos de entrada

Layouts

DocsLayout

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

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.

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.

import { DocsBody } from "onedocs";

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

HomePage

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

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 e o rodapé para saber o que a configuração controla.

HomeLayout

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

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.

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.

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.

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.

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.

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.

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:

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

GitHubIcon

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

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.

import { CodeBlock } from "onedocs";

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

Configuração

defineConfig

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

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Tipo TypeScript para configuração.

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

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

Consulte Configuração para ver todas as opções.

Utilitários de origem

loader

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

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.

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). Use loader como mostrado acima até que isso seja corrigido.

Metadados

createMetadata

Gera metadados Next.js para o layout raiz.

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.

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.

Imagens OpenGraph

createRootOGImage

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

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

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

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

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.

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

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

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

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

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

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

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.

Consulte Componentes para ver exemplos de uso.