# Riferimento di API

Riferimento completo per tutte le esportazioni dal pacchetto `onedocs`.

## Punti di accesso

| Importazione | Descrizione |
|--------|-------------|
| `onedocs` | Punto di accesso principale: layout, componenti, `mdxComponents`, `defineConfig`, helper per le sorgenti |
| `onedocs/components` | Componenti Fumadocs UI più `InstallBlock`, `CodeBlock`, `Button` e `Logo` |
| `onedocs/config` | Helper di configurazione |
| `onedocs/source` | Utility per le sorgenti di contenuti |
| `onedocs/metadata` | Generazione dei metadati |
| `onedocs/og` | Generazione di immagini OpenGraph |
| `onedocs/llms` | Generazione di LLMs.txt |
| `onedocs/seo` | Sitemap e robots.txt |
| `onedocs/css/preset.css` | Preset Tailwind CSS |

## Layout

### DocsLayout

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

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

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

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

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

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

### HomePage

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

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

**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](https://onedocs.inline0.dev/it/docs/configuration#homepage) e il [footer](https://onedocs.inline0.dev/it/docs/configuration#footer) per sapere cosa controlla la configurazione.

### HomeLayout

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

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

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

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

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

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

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

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

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

### GitHubIcon

Componente icona GitHub (usato internamente nella navigazione).

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

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

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

## Configurazione

### defineConfig

Helper di configurazione con sicurezza dei tipi.

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

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

### OnedocsConfig

Tipo TypeScript per la configurazione.

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

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

Consultate la sezione [Configurazione](https://onedocs.inline0.dev/it/docs/configuration) per tutte le opzioni.

## Utility per le sorgenti

### loader

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

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

```tsx
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](https://github.com/inline0/onedocs/issues/4)). Usate `loader` come mostrato sopra finché il problema non sarà risolto.

## Metadati

### createMetadata

Genera i metadati Next.js per il layout radice.

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

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

Per un'immagine Open Graph specifica della pagina, consultate [Immagini OG dinamiche](#dynamic-og-images).

## Immagini OpenGraph

### createRootOGImage

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

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

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

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

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

### Funzioni helper

| Funzione | Descrizione |
|----------|-------------|
| `loadPublicFile(path)` | Carica un file da `public/` come dati URL e buffer; per i file SVG legge anche gli attributi `width` e `height` |
| `loadInterFont(path?)` | Carica un font da `public/` per le immagini OG, `fonts/Inter-Medium.ttf` per impostazione predefinita |
| `ogImageSize` | Dimensioni standard delle immagini OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Tipo MIME `"image/png"` |

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

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

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.

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

I corpi delle pagine vengono inclusi solo quando Fumadocs MDX di `includeProcessedMarkdown` è attivo; vedi [SEO e Ricerca](https://onedocs.inline0.dev/it/docs/seo-search#full-content-version).

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

```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 ?? [],
  });
}
```

Consultate [SEO e Ricerca](https://onedocs.inline0.dev/it/docs/seo-search#sitemap) 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`.

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

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

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

Consultate [Componenti](https://onedocs.inline0.dev/it/docs/components) per esempi d'uso.