Riferimento di API

Riferimento completo per tutte le esportazioni dal pacchetto onedocs.

Punti di accesso

Layout

DocsLayout

Wrapper del layout principale per le pagine della documentazione. Fornisce navigazione laterale, ricerca e selettore del tema.

import { DocsLayout } from "onedocs";

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

Proprietà:

• config - Il vostro oggetto OnedocsConfig
• pageTree - Albero delle pagine dalla vostra sorgente (e.g, source.pageTree)
• children - Contenuto della pagina

DocsPage

Wrapper per le singole pagine della documentazione. Avvolge Fumadocs UI DocsPage e inserisce il contenuto in 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>
  );
}

Proprietà:

• toc - Indice dei contenuti ricavato dai dati della pagina
• children - Contenuto MDX
• Qualsiasi altra proprietà di Fumadocs UI DocsPage, come full

DocsBody

Wrapper interno per il corpo dei contenuti della documentazione. Usato internamente da DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Componente completo per la pagina iniziale, con hero, funzionalità e piè di pagina.

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

Proprietà:

• config - Il vostro oggetto OnedocsConfig
• packageName - Nome del pacchetto per il blocco di installazione (facoltativo)
• children - Contenuto tra le funzionalità e il piè di pagina (facoltativo)

Consultate la homepage e il footer per sapere cosa controlla la configurazione.

HomeLayout

Layout di base per la homepage (usato internamente da HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Crea le opzioni di layout Fumadocs UI (titolo o logo della barra di navigazione, nav.links e link GitHub) dalla configurazione. DocsLayout e HomeLayout lo usano; chiamatelo direttamente quando renderizzate un layout Fumadocs UI.

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

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

Componenti

InstallBlock

Schede del gestore di pacchetti con i comandi di installazione per npm, yarn, pnpm e bun (npm i, yarn add, pnpm add, bun add). È un componente server asincrono.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Proprietà:

• packageName - Nome del pacchetto npm da installare
• title - Titolo sopra le schede (facoltativo)
• description - Testo sopra le schede (facoltativo)
• children - Contenuto sotto le schede (facoltativo)

Button

Link arrotondato con lo stile di un pulsante principale. È disponibile un solo stile.

import { Button } from "onedocs";

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

Proprietà:

• href - Destinazione del link
• children - Testo del pulsante
• className - Classi aggiuntive (facoltative)

Logo

Visualizza un'immagine chiara e una scura, mostrando quella corrispondente al tema corrente. DocsLayout e HomePage lo usano per un logo con varianti chiare e scure.

import { Logo } from "onedocs";

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

Proprietà:

• light - Percorso dell'immagine per la modalità chiara
• dark - Percorso dell'immagine per la modalità scura
• alt - Testo alternativo (predefinito: "Logo")
• className - Classi per entrambe le immagini (facoltative)

CTASection

Sezione di invito all'azione per la homepage.

import { CTASection } from "onedocs";

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

Proprietà:

• title - Titolo della sezione
• description - Testo sotto il titolo (facoltativo)
• cta - Configurazione del pulsante con label e href
• children - Contenuto sotto il pulsante (facoltativo)

FontHead

Precarica il font Inter Variable, ne dichiara @font-face e lo imposta come font della pagina. Aggiungetelo a <head> del layout radice.

import { FontHead } from "onedocs";

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

Onedocs non include il font. Per impostazione predefinita, FontHead carica /fonts/InterVariable.woff2: inserite quindi il file in public/fonts/ oppure passate un altro URL con fontPath:

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

GitHubIcon

Componente icona GitHub (usato internamente nella navigazione).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Blocco di codice con evidenziazione della sintassi sul server tramite Shiki e Fumadocs. È un componente server asincrono.

import { CodeBlock } from "onedocs";

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

Configurazione

defineConfig

Helper di configurazione con sicurezza dei tipi.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Tipo TypeScript per la configurazione.

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

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

Consultate la sezione Configurazione per tutte le opzioni.

Utility per le sorgenti

loader

Nuova esportazione del loader fumadocs-core/source per creare sorgenti di contenuti.

import { loader } from "onedocs/source";

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

createSource

Helper per creare una sorgente di contenuti (wrapper del loader). La sorgente URL di base è /docs per impostazione predefinita.

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

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

In 0.1.27, createSource restituisce una sorgente senza tipi, quindi TypeScript segnala errori come Property 'data' does not exist on type 'unknown' quando leggete page.data (#4). Usate loader come mostrato sopra finché il problema non sarà risolto.

Metadati

createMetadata

Genera i metadati Next.js per il layout radice.

import { createMetadata } from "onedocs/metadata";

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

Opzioni:

• baseUrl - URL di base del vostro sito (facoltativo)
• additional - Campi Metadata aggiuntivi, uniti per ultimi (facoltativi)

Restituisce: un oggetto Next.js Metadata con:

• Titolo (config.title) e modello del titolo (%s | Site Name)
• Descrizione
• Favicon da config.icon, se impostata
• Se baseUrl è impostato: metadataBase, metadati OpenGraph e una scheda Twitter summary_large_image

createDocsPageMetadata

Genera i metadati di titolo e descrizione per una pagina della documentazione. Accetta un oggetto con title e un description facoltativo.

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

Per un'immagine Open Graph specifica della pagina, consultate Immagini OG dinamiche.

Immagini OpenGraph

createRootOGImage

Crea un'immagine OG per la homepage: il vostro logo centrato su uno sfondo nero.

// 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 un'immagine OG per le pagine della documentazione: logo in alto a sinistra e titolo bianco su sfondo nero. L'argomento del font è facoltativo; senza, il titolo usa il font di 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);
}

Immagini OG dinamiche

Per immagini OG specifiche di ogni pagina, servitele da una route. Le pagine non vengono indirizzate automaticamente a questa route: aggiungetela manualmente ai metadati di ogni pagina, ad esempio con openGraph: { images: "/docs/og/getting-started" } insieme ai campi di 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);
}

Funzioni helper

File richiesti:

• public/logo-dark.svg - Logo per le immagini OG. Gli helper OG ne ricavano le dimensioni dagli attributi width e height, quindi il tag <svg> deve contenere entrambi come numeri semplici.
• public/fonts/Inter-Medium.ttf - Font per i titoli. Onedocs non lo include.

LLMs.txt

Genera file LLMs.txt per gli assistenti IA.

generateLLMsText

Genera contenuti LLMs.txt concisi. Accetta una sorgente avvolta da createLLMsSource e { title, description? } e restituisce una promise.

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

Gli URL delle pagine vengono riportati così come provengono dalla sorgente, ad esempio /docs/getting-started, senza dominio.

generateLLMsFullText

Genera LLMs.txt completo con tutti i contenuti delle pagine. Accetta solo la sorgente avvolta e restituisce una promise.

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

I corpi delle pagine vengono inclusi solo quando Fumadocs MDX di includeProcessedMarkdown è attivo; vedi SEO e Ricerca.

createLLMsSource

Avvolge una sorgente Fumadocs (risultato loader() o createSource()) nella struttura letta dalle due funzioni sopra: i loader URL, del titolo, della descrizione e del testo di ogni pagina.

SEO

generateSitemap

Genera una sitemap per la documentazione. Accetta un oggetto con baseUrl, l'elenco pages (di solito da meta.json) e un docsPath facoltativo (predefinito /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 ?? [],
  });
}

Consultate SEO e Ricerca per sapere come le voci diventano URL.

generateRobots

Genera contenuti robots.txt: consente tutto, oltre alle righe Host e Sitemap. Per impostazione predefinita, sitemapPath è /sitemap.xml.

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

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

Preset CSS

Importate il preset CSS nel vostro globals.css:

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

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

I percorsi @source sono relativi a src/app/globals.css.

Il preset include:

• Tailwind CSS v4 (installate tailwindcss e @tailwindcss/postcss autonomamente)
• Tema neutro Fumadocs
• Stili preset Fumadocs
• --font-sans impostato sulla variabile --font-inter definita da FontHead
• Funzionalità OpenType Inter per il testo del corpo e i titoli
• Stili di layout a tutta altezza e modifiche al layout Onedocs

Componenti MDX

L’esportazione di mdxComponents estende i componenti predefiniti Fumadocs UI di MDX e aggiunge i componenti seguenti:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Componenti inclusi:

• Predefiniti Fumadocs UI: pre (blocchi di codice), a, img, da h1 a h6 (titoli con ancore), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Riquadri informativi, di avviso e di errore
• Card, Cards - Layout a schede
• Tab, Tabs - Contenuti a schede
• Step, Steps - Passaggi numerati
• Accordion, Accordions - Sezioni comprimibili
• File, Folder, Files - Strutture ad albero dei file
• ImageZoom - Immagini con zoom
• TypeTable - Tabelle di documentazione dei tipi

InstallBlock e CodeBlock non sono inclusi; aggiungeteli come indicato nella sezione Componenti.

Consultate Componenti per esempi d'uso.