# SEO e ricerca

La ricerca è fornita da Fumadocs. Onedocs aggiunge helper per sitemap, file robots.txt e llms.txt, tutti configurati come route App Router Next.js. Per i metadati delle pagine e le immagini Open Graph, consultate `onedocs/metadata` e `onedocs/og` nel [API Reference](https://onedocs.inline0.dev/it/docs/api-reference#metadata).

## Ricerca

Onedocs usa la ricerca Orama integrata di Fumadocs. Create una route API:

```ts title="src/app/api/search/route.ts"
import { source } from "@/lib/source";
import { createFromSource } from "fumadocs-core/search/server";

export const { GET } = createFromSource(source);
```

Per impostazione predefinita, il dialogo di ricerca aggiunto da `RootProvider` interroga `/api/search`, quindi non serve altra configurazione.

## Sitemap

Generate una sitemap in `/sitemap.xml`:

```ts title="src/app/sitemap.ts"
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

const baseUrl = "https://yourdomain.com";

export default function sitemap() {
  return generateSitemap({
    baseUrl,
    pages: meta.pages ?? [],
  });
}
```

`generateSitemap` elenca la radice del sito, quindi un URL per ogni voce in `pages` sotto `/docs`. Le voci che iniziano con `---` (separatori della barra laterale) vengono ignorate e `index` punta alla cartella stessa `/docs`. Le voci vengono lette così come sono, quindi le pagine nelle sottocartelle devono avere voci proprie, per esempio `"guides/setup"`.

## Robots.txt

Generate un robots.txt in `/robots.txt`:

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

const baseUrl = "https://yourdomain.com";

export default function robots() {
  return generateRobots({ baseUrl });
}
```

Vengono creati:

```
User-Agent: *
Allow: /

Host: https://yourdomain.com
Sitemap: https://yourdomain.com/sitemap.xml
```

## LLMs.txt

[LLMs.txt](https://llmstxt.org/) aiuta gli assistenti IA a comprendere la documentazione. Onedocs può generare sia una versione riassuntiva sia una con tutti i contenuti.

### Versione riassuntiva

Create `/llms.txt` con titoli e descrizioni delle pagine:

```ts title="src/app/llms.txt/route.ts"
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";
import config from "../../../onedocs.config";

export async function GET() {
  const llmsSource = createLLMsSource(source);
  const text = await generateLLMsText(llmsSource, {
    title: config.title,
    description: config.description,
  });

  return new Response(text, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

Il file inizia con titolo e descrizione, elenca ogni pagina come `- Title: URL` con la relativa descrizione e termina con un riferimento a `/llms-full.txt`. Entrambe le funzioni ricevono la sorgente avvolta da `createLLMsSource`, non la sorgente Fumadocs stessa, e restituiscono una promise.

### Versione con tutti i contenuti

Create `/llms-full.txt` con la documentazione completa:

```ts title="src/app/llms-full.txt/route.ts"
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const llmsSource = createLLMsSource(source);
  const text = await generateLLMsFullText(llmsSource);

  return new Response(text, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

Ogni pagina viene scritta con titolo, URL, descrizione e Markdown elaborato, separata dalla successiva da `---`.

Il testo delle pagine proviene da Fumadocs MDX, il cui Markdown elaborato è disattivato per impostazione predefinita. Senza questa opzione, `llms-full.txt` contiene solo titoli, URL e descrizioni ([#3](https://github.com/inline0/onedocs/issues/3)). Attivatela in `source.config.ts`:

```ts title="source.config.ts"
import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});
```

## Opzioni di configurazione

### Opzioni della sitemap

```ts
generateSitemap({
  baseUrl: "https://yourdomain.com",
  pages: ["index", "getting-started", "configuration"],
  docsPath: "/docs", // Default: "/docs"
});
```

### Opzioni di robots

```ts
generateRobots({
  baseUrl: "https://yourdomain.com",
  sitemapPath: "/sitemap.xml", // Default: "/sitemap.xml"
});
```

## Cosa offre

Dopo aver configurato queste route:

| URL | Funzione |
|-----|--------------|
| `/api/search?query=...` | Endpoint di ricerca API |
| `/sitemap.xml` | Sitemap XML per i motori di ricerca |
| `/robots.txt` | File robots con riferimento alla sitemap |
| `/llms.txt` | Riepilogo per gli assistenti IA |
| `/llms-full.txt` | Documentazione completa per gli assistenti IA |