# Référence API

Référence complète de tous les exports du package `onedocs`.

## Points d’entrée

| Import | Description |
|--------|-------------|
| `onedocs` | Point d’entrée principal : mises en page, composants, `mdxComponents`, `defineConfig`, utilitaires source |
| `onedocs/components` | Composants Fumadocs UI et `InstallBlock`, `CodeBlock`, `Button` et `Logo` |
| `onedocs/config` | Utilitaires de configuration |
| `onedocs/source` | Utilitaires de source de contenu |
| `onedocs/metadata` | Génération des métadonnées |
| `onedocs/og` | Génération d’images OpenGraph |
| `onedocs/llms` | Génération de LLMs.txt |
| `onedocs/seo` | Plan de site et robots.txt |
| `onedocs/css/preset.css` | Préréglage Tailwind CSS |

## Mises en page

### DocsLayout

Conteneur de mise en page principal des pages de documentation. Il fournit une navigation latérale, une recherche et un sélecteur de thème.

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

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

**Propriétés :**
- `config` - Votre objet `OnedocsConfig`
- `pageTree` - Arborescence des pages de votre source (e.g., `source.pageTree`)
- `children` - Contenu de la page

### DocsPage

Conteneur pour les pages de documentation individuelles. Il enveloppe le Fumadocs UI `DocsPage` et place le contenu dans `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>
  );
}
```

**Propriétés :**
- `toc` - Table des matières issue des données de la page
- `children` - Contenu MDX
- Toute autre propriété de Fumadocs UI `DocsPage`, telle que `full`

### DocsBody

Conteneur interne du corps du contenu de la documentation. Utilisé en interne par `DocsPage`.

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

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

### HomePage

Composant complet de page d’accueil avec une section principale, des fonctionnalités et un pied de page.

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

**Propriétés :**
- `config` - Votre objet `OnedocsConfig`
- `packageName` - Nom du package pour le bloc d’installation (facultatif)
- `children` - Contenu entre les fonctionnalités et le pied de page (facultatif)

Consultez [la page d’accueil](https://onedocs.inline0.dev/fr/docs/configuration#homepage) et [le pied de page](https://onedocs.inline0.dev/fr/docs/configuration#footer) pour savoir ce que contrôle la configuration.

### HomeLayout

Mise en page de base de la page d’accueil (utilisée en interne par `HomePage`).

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

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

### createBaseOptions

Génère les options de mise en page de Fumadocs UI (titre ou logo de la barre de navigation, `nav.links` et lien GitHub) à partir de votre configuration. `DocsLayout` et `HomeLayout` les utilisent ; appelez cette fonction vous-même lorsque vous affichez directement une mise en page Fumadocs UI.

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

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

## Composants

### InstallBlock

Onglets de gestionnaires de packages affichant les commandes d’installation pour npm, yarn, pnpm et bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Il s’agit d’un composant serveur asynchrone.

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

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

**Propriétés :**
- `packageName` - Nom du package npm à installer
- `title` - Titre au-dessus des onglets (facultatif)
- `description` - Texte au-dessus des onglets (facultatif)
- `children` - Contenu sous les onglets (facultatif)

### Button

Lien arrondi présenté comme un bouton principal. Un seul style est disponible.

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

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

**Propriétés :**
- `href` - Destination du lien
- `children` - Texte du bouton
- `className` - Classes supplémentaires (facultatif)

### Logo

Affiche une image claire et une image sombre, puis montre celle qui correspond au thème actuel. `DocsLayout` et `HomePage` l’utilisent pour un `logo` avec des variantes claires et sombres.

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

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

**Props :**
- `light` - Chemin de l’image pour le mode clair
- `dark` - Chemin de l’image pour le mode sombre
- `alt` - Texte alternatif (par défaut : `"Logo"`)
- `className` - Classes pour les deux images (facultatif)

### CTASection

Section d’appel à l’action pour la page d’accueil.

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

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

**Props :**
- `title` - Titre de la section
- `description` - Texte sous le titre (facultatif)
- `cta` - Configuration du bouton avec `label` et `href`
- `children` - Contenu sous le bouton (facultatif)

### FontHead

Précharge la police Inter Variable, déclare son `@font-face` et la définit comme police de la page. Ajoutez-la au `<head>` de votre mise en page racine.

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

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

Onedocs ne fournit pas la police. Par défaut, `FontHead` charge `/fonts/InterVariable.woff2` ; placez donc le fichier dans `public/fonts/`, ou transmettez un autre URL avec `fontPath` :

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

### GitHubIcon

Composant d’icône GitHub (utilisé en interne dans la navigation).

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

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

### CodeBlock

Bloc de code avec coloration syntaxique, coloré sur le serveur avec Shiki via Fumadocs. Il s’agit d’un composant serveur asynchrone.

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

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

## Configuration

### defineConfig

Assistant de configuration à types sûrs.

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

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

### OnedocsConfig

Type TypeScript pour la configuration.

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

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

Consultez [Configuration](https://onedocs.inline0.dev/fr/docs/configuration) pour voir toutes les options.

## Utilitaires de source

### loader

Réexportation du chargeur `fumadocs-core/source` pour créer des sources de contenu.

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

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

### createSource

Assistant de création d’une source de contenu (encapsulation du chargeur). La base URL est `/docs` par défaut.

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

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

Dans 0.1.27, `createSource` renvoie une source non typée ; TypeScript signale donc des erreurs telles que `Property 'data' does not exist on type 'unknown'` lorsque vous lisez `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Utilisez `loader` comme indiqué ci-dessus jusqu’à ce que le problème soit résolu.

## Métadonnées

### createMetadata

Génère les métadonnées Next.js pour votre mise en page racine.

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

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

**Options :**
- `baseUrl` - URL de base de votre site URL (facultatif)
- `additional` - Champs `Metadata` supplémentaires, fusionnés en dernier (facultatif)

**Renvoie :** un objet Next.js `Metadata` avec :
- Titre (`config.title`) et modèle de titre (`%s | Site Name`)
- Description
- Icône de favori provenant de `config.icon`, si défini
- Si `baseUrl` est défini : `metadataBase`, métadonnées OpenGraph et carte Twitter `summary_large_image`

### createDocsPageMetadata

Génère les métadonnées de titre et de description d’une page de documentation. Prend un objet avec `title` et un `description` facultatif.

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

Pour une image Open Graph propre à une page, consultez [Images OG dynamiques](#dynamic-og-images).

## Images OpenGraph

### createRootOGImage

Crée une image OG pour la page d’accueil : votre logo centré sur un fond noir.

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

Crée une image OG pour les pages de documentation : le logo en haut à gauche et le titre en blanc sur fond noir. L’argument de police est facultatif ; sans lui, le titre utilise la police système.

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

### Images OG dynamiques

Pour les images OG propres à chaque page, servez-les depuis une route. Aucune page ne pointe automatiquement vers cette route : ajoutez-la vous-même aux métadonnées de chaque page, par exemple avec `openGraph: { images: "/docs/og/getting-started" }` à côté des champs 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);
}
```

### Fonctions d’assistance

| Fonction | Description |
|----------|-------------|
| `loadPublicFile(path)` | Charge un fichier depuis `public/` sous forme de données URL et de tampon ; pour les SVG, lit également les attributs `width` et `height` |
| `loadInterFont(path?)` | Charge une police depuis `public/` pour les images OG, `fonts/Inter-Medium.ttf` par défaut |
| `ogImageSize` | Dimensions standard des images OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Type MIME standard `"image/png"` |

**Fichiers requis :**
- `public/logo-dark.svg` - Logo pour les images OG. Les fonctions d’assistance OG le dimensionnent à partir de ses attributs `width` et `height` ; la balise `<svg>` doit donc contenir les deux sous forme de nombres simples.
- `public/fonts/Inter-Medium.ttf` - Police pour les titres. Onedocs ne la fournit pas.

## LLMs.txt

Générer des fichiers LLMs.txt pour les assistants IA.

### generateLLMsText

Génère un contenu LLMs.txt concis. Prend une source encapsulée avec `createLLMsSource` et `{ title, description? }`, et renvoie une promesse.

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

Les URL des pages sont reprises telles quelles depuis la source, par exemple `/docs/getting-started`, sans domaine.

### generateLLMsFullText

Génère un LLMs.txt complet avec le contenu intégral des pages. Prend uniquement la source encapsulée et renvoie une promesse.

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

Le corps des pages est inclus uniquement si Fumadocs de MDX a la valeur `includeProcessedMarkdown` ; consultez [SEO et recherche](https://onedocs.inline0.dev/fr/docs/seo-search#full-content-version).

### createLLMsSource

Encapsule une source Fumadocs (résultat `loader()` ou `createSource()`) dans la structure attendue par les deux fonctions ci-dessus : le URL de chaque page, son titre, sa description et ses chargeurs de texte.

## SEO

### generateSitemap

Génère un plan de site pour votre documentation. Prend un objet avec `baseUrl`, la liste `pages` (généralement issue de `meta.json`) et un `docsPath` facultatif (par défaut `/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 ?? [],
  });
}
```

Consultez [SEO et recherche](https://onedocs.inline0.dev/fr/docs/seo-search#sitemap) pour savoir comment les entrées deviennent des URL.

### generateRobots

Génère du contenu robots.txt : tout autoriser, plus les lignes `Host` et `Sitemap`. `sitemapPath` est défini par défaut sur `/sitemap.xml`.

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

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

## Préréglage CSS

Importez le préréglage CSS dans votre `globals.css` :

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

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

Les chemins `@source` sont relatifs à `src/app/globals.css`.

Le préréglage comprend :
- Tailwind CSS v4 par défaut (installez vous-même `tailwindcss` et `@tailwindcss/postcss`)
- Thème neutre Fumadocs
- Styles du préréglage Fumadocs
- `--font-sans` défini sur la variable `--font-inter` définie par `FontHead`
- Fonctionnalités OpenType d’Inter pour le corps du texte et les titres
- Styles de mise en page pleine hauteur et ajustements de mise en page Onedocs

## Composants MDX

L’export `mdxComponents` étend les composants par défaut Fumadocs UI MDX et ajoute les composants ci-dessous :

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

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

**Composants inclus :**
- Valeurs par défaut de Fumadocs UI : `pre` (blocs de code), `a`, `img`, de `h1` à `h6` (titres avec ancres), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` - Encadrés d’information, d’avertissement et d’erreur
- `Card`, `Cards` - Mises en page en cartes
- `Tab`, `Tabs` - Contenu à onglets
- `Step`, `Steps` - Étapes numérotées
- `Accordion`, `Accordions` - Sections repliables
- `File`, `Folder`, `Files` - Arborescences de fichiers
- `ImageZoom` - Images avec zoom
- `TypeTable` - Tableaux de documentation des types

`InstallBlock` et `CodeBlock` ne sont pas inclus ; ajoutez-les vous-même comme indiqué dans [Composants](https://onedocs.inline0.dev/fr/docs/components#more-components).

Consultez [Composants](https://onedocs.inline0.dev/fr/docs/components) pour des exemples d’utilisation.