# Premiers pas

Ce guide vous accompagne dans la création d’un site de documentation avec Onedocs dans un dossier vide. Si vous avez déjà un projet Next.js, ignorez les fichiers déjà présents et comparez les autres.

## Prérequis

- Node.js 20.9 ou version ultérieure (requis par Next.js 16)
- Next.js 16 avec App Router, React 19.2 ou version ultérieure
- Tailwind CSS v4 (le préréglage Onedocs CSS importe `tailwindcss`)

Fumadocs UI 16 ne prend en charge que Next.js 16 et React 19.2 ; les versions antérieures de Next.js ou React ne fonctionnent donc pas, même si les métadonnées du paquet `onedocs` les répertorient encore ([#5](https://github.com/inline0/onedocs/issues/5)).

## Installation

Onedocs n’intègre ni Next.js ni Fumadocs. Ce sont des dépendances homologues, à installer à ses côtés :

```bash
npm install onedocs fumadocs-core fumadocs-mdx fumadocs-ui lucide-react@0.562 next react react-dom
npm install -D tailwindcss @tailwindcss/postcss typescript @types/react @types/react-dom @types/node
```

Conservez l’épinglage `lucide-react@0.562`. `onedocs` 0.1.27 déclare `lucide-react` `^0.562.0` comme dépendance homologue ; sans cet épinglage, npm installe lucide-react 1.x et s’arrête avec une erreur `ERESOLVE` ([#1](https://github.com/inline0/onedocs/issues/1)).

Les mêmes paquets fonctionnent avec pnpm, yarn ou bun.

Ajoutez les scripts Next.js à `package.json` :

```json title="package.json"
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
```

## Structure du projet

Voici la structure que vous obtiendrez :

```
your-project/
├── content/
│   └── docs/
│       ├── index.mdx
│       └── meta.json
├── public/
│   └── fonts/
│       └── InterVariable.woff2
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   └── docs/
│   │       ├── layout.tsx
│   │       └── [[...slug]]/
│   │           └── page.tsx
│   └── lib/
│       └── source.ts
├── onedocs.config.ts
├── source.config.ts
├── next.config.mjs
├── postcss.config.mjs
├── tsconfig.json
└── package.json
```

Créons chaque fichier.

## Fichiers de configuration

### onedocs.config.ts

Votre fichier de configuration principal. Seul `title` est obligatoire ; consultez [Configuration](https://onedocs.inline0.dev/fr/docs/configuration) pour le reste.

```ts title="onedocs.config.ts"
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project",
  nav: {
    github: "username/repo",
  },
});
```

### source.config.ts

Indique à Fumadocs MDX où se trouve votre contenu. C’est le seul endroit où le dossier de contenu est défini :

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

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

### next.config.mjs

Active le traitement MDX :

```js title="next.config.mjs"
import { createMDX } from "fumadocs-mdx/next";

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {};

export default withMDX(config);
```

Fumadocs MDX génère un dossier `.source/` à partir de `source.config.ts` au démarrage de Next.js. Ajoutez `.source` à `.gitignore`.

### postcss.config.mjs

Exécute Tailwind CSS v4, sur lequel repose le préréglage Onedocs CSS :

```js title="postcss.config.mjs"
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
```

### tsconfig.json

Les exemples ci-dessous importent depuis `@/` ; associez-le donc à `src/` :

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Next.js ajoute à ce fichier les options de compilation restantes nécessaires lors de la première exécution de `next dev` ou `next build`.

## Configuration de la source

### src/lib/source.ts

Charge le contenu de votre documentation :

```ts title="src/lib/source.ts"
import { loader } from "fumadocs-core/source";
import { docs } from "../../.source/server";

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

## Fichiers de l’application

### src/app/layout.tsx

Votre mise en page racine :

```tsx title="src/app/layout.tsx"
import type { Metadata } from "next";
import { RootProvider } from "fumadocs-ui/provider/next";
import { FontHead } from "onedocs";
import "./globals.css";

export const metadata: Metadata = {
  title: "My Docs",
  description: "Documentation for my project",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <FontHead />
      </head>
      <body className="antialiased">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}
```

`RootProvider` de Fumadocs UI fournit la boîte de dialogue de recherche et les thèmes clair et sombre. `FontHead` précharge la police Inter Variable depuis `/fonts/InterVariable.woff2` et la définit comme police de la page. Onedocs ne fournit pas le fichier de police : téléchargez `InterVariable.woff2` depuis [les versions d’Inter](https://github.com/rsms/inter/releases) et placez-le dans `public/fonts/`. Sans cela, le texte utilise la police sans empattement du système.

Pour générer ces métadonnées à partir de votre configuration, consultez `createMetadata` dans la [référence API](https://onedocs.inline0.dev/fr/docs/api-reference#createmetadata).

### src/app/globals.css

Importez le préréglage CSS :

```css title="src/app/globals.css"
@import "onedocs/css/preset.css";

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

Le préréglage charge Tailwind CSS, les styles Fumadocs UI et les styles de mise en page Onedocs. Les chemins `@source` sont relatifs à `globals.css` ; ces deux lignes pointent donc vers `src/app/` et vers le dossier `content/` à la racine du projet.

### src/app/page.tsx

La page d’accueil. `HomePage` affiche la bannière, les fonctionnalités et le pied de page à partir de votre configuration :

```tsx title="src/app/page.tsx"
import { HomePage } from "onedocs";
import config from "../../onedocs.config";

export default function Home() {
  return <HomePage config={config} packageName="my-package" />;
}
```

`packageName` ajoute à la bannière les commandes d’installation pour npm, yarn, pnpm et bun. Omettez-le si votre projet n’est pas un paquet.

### src/app/docs/layout.tsx

Mise en page de la documentation avec barre latérale :

```tsx title="src/app/docs/layout.tsx"
import { DocsLayout } from "onedocs";
import type { ReactNode } from "react";
import { source } from "@/lib/source";
import config from "../../../onedocs.config";

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

### src/app/docs/[[...slug]]/page.tsx

Pages de documentation individuelles :

```tsx title="src/app/docs/[[...slug]]/page.tsx"
import { source } from "@/lib/source";
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>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}
```

## Contenu

### content/docs/index.mdx

Chaque page nécessite un `title` dans son frontmatter. Le `description` est facultatif :

```mdx title="content/docs/index.mdx"
---
title: Introduction
description: What this project does.
---

Welcome to the docs. Components such as `<Callout>` work without imports; see [Components](/docs/components).
```

### content/docs/meta.json

Définit l’ordre de la barre latérale :

```json title="content/docs/meta.json"
{
  "pages": ["index"]
}
```

Ajoutez une page en créant un autre fichier `.mdx` et en indiquant son nom dans `pages`.

## Exécution

Démarrez le serveur de développement :

```bash
npm run dev
```

La page d’accueil se trouve à `http://localhost:3000` et la documentation à `http://localhost:3000/docs`.

Générez la version de production :

```bash
npm run build
```

Ajoutez ensuite la recherche, un plan de site et llms.txt dans [SEO et recherche](https://onedocs.inline0.dev/fr/docs/seo-search).