---
title: "Configuration"
description: "Personnalisez votre documentation Docus depuis le fichier de configuration Nuxt de l'application. "
canonical_url: "https://docus.dev/fr/concepts/configuration"
---
# Configuration

> Personnalisez votre documentation Docus depuis le fichier de configuration Nuxt de l'application.

Docus vous permet de configurer votre documentation via le fichier [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config) fourni par Nuxt.

<warning>

Un fichier `nuxt.config.ts` doit être existant pour surcharger votre app config. Sans le fichier Nuxt config, vos surcharges ne seront pas prises en compte.

</warning>

## SEO

Le SEO technique est complexe et fastidieux. Docus propose une configuration par défaut solide et optionnelle qui fonctionne immédiatement, tout en vous laissant la possibilité de personnaliser entièrement vos métadonnées SEO, des titres de page aux images de partage social.

### Métadonnées

Docus offre une configuration flexible des métadonnées `SEO`, vous permettant de facilement surcharger les valeurs globalement ou page par page.

#### Configuration globale

Définissez les métadonnées `SEO` par défaut pour toute votre documentation dans `app.config.ts`. Ces valeurs seront utilisées comme valeurs de repli pour les pages qui ne spécifient pas leurs propres valeurs dans le frontmatter, comme décrit dans la section suivante.

Vous pouvez aussi configurer la valeur `site.name` depuis votre fichier `nuxt.config.ts`, la valeur par défaut étant basée sur le nom de votre `package.json`.

<code-group>

```ts [app.config.ts]
export default defineAppConfig({
  seo: {
    // Par défaut : `%s - ${site.name}`
    titleTemplate: ''
    // Par défaut : nom du package.json
    title: '',
    // Par défaut : description du package.json
    description: ''
  },
})
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  site: {
    name: 'Docus',
  },
})
```

</code-group>

#### Configuration par page

Chaque fichier Markdown du dossier `content/` commence par un bloc frontmatter (`---`). Vous pouvez définir les métadonnées `SEO` par page en utilisant la clé `seo` :

```md [content/concepts/configuration.md]
---
seo:
  title: 'Configuration'
  description: 'Personnalisez votre documentation Docus depuis le fichier de configuration Nuxt de l'application.'
---

<!-- Contenu de la page -->
```

<tip to="https://docus.dev/fr/concepts/edition#frontmatter">

Pour plus de détails sur le frontmatter, consultez le guide d'édition.

</tip>

### Données structurées

Docus génère du [JSON-LD](https://json-ld.org) avec [`nuxt-schema-org`](https://nuxtseo.com/docs/schema-org) :

- `WebSite` et `WebPage` sur chaque page
- `TechArticle` et `BreadcrumbList` sur les pages de documentation

Les moteurs de recherche et les agents IA s'appuient dessus pour identifier une page sans analyser votre balisage.

La page d'accueil peut aussi décrire ce qu'*est* votre site. Ajoutez `seo.schema` et Docus génère un graphe liant votre produit et l'organisation derrière lui :

```ts [app.config.ts]
export default defineAppConfig({
  seo: {
    schema: {
      type: 'SoftwareApplication',
      applicationCategory: 'DeveloperApplication',
      price: 0,
      sameAs: [
        'https://github.com/nuxt-content/docus',
        'https://www.npmjs.com/package/docus',
      ],
      organization: {
        name: 'Nuxt',
        url: 'https://nuxt.com',
        logo: '/logo/logo-dark.svg',
        sameAs: ['https://github.com/nuxt'],
      },
    },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      Ce qu'est le site : <code>
        SoftwareApplication
      </code>
      
      , <code>
        Product
      </code>
      
      , <code>
        Organization
      </code>
      
       ou <code>
        Person
      </code>
      
      . Sans cette valeur, seul <code>
        WebSite
      </code>
      
       est généré.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sameAs
      </code>
    </td>
    
    <td>
      URLs de profils canoniques (GitHub, npm, X, LinkedIn), utilisées pour recouper votre identité entre les sources.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        applicationCategory
      </code>
    </td>
    
    <td>
      Catégorie de l'application, <code>
        DeveloperApplication
      </code>
      
       par défaut. Uniquement pour <code>
        SoftwareApplication
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        operatingSystem
      </code>
    </td>
    
    <td>
      Plateformes sur lesquelles elle fonctionne, <code>
        Web
      </code>
      
       par défaut. Uniquement pour <code>
        SoftwareApplication
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        price
      </code>
    </td>
    
    <td>
      Prix de l'application. Mettez <code>
        0
      </code>
      
       pour indiquer qu'elle est gratuite. Uniquement pour <code>
        SoftwareApplication
      </code>
      
       et <code>
        Product
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        priceCurrency
      </code>
    </td>
    
    <td>
      Devise ISO 4217 pour <code>
        price
      </code>
      
      , <code>
        USD
      </code>
      
       par défaut.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organization
      </code>
    </td>
    
    <td>
      Éditeur du site, généré comme <code>
        Organization
      </code>
      
       liée. Accepte <code>
        name
      </code>
      
      , <code>
        url
      </code>
      
      , <code>
        logo
      </code>
      
      , <code>
        sameAs
      </code>
      
      , <code>
        address
      </code>
      
       et <code>
        contactPoint
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organization.parentOrganization
      </code>
    </td>
    
    <td>
      L'entreprise à laquelle appartient l'éditeur, imbriquée dans l'<code>
        Organization
      </code>
      
       de l'éditeur.
    </td>
  </tr>
</tbody>
</table>

<note>

Toutes les options `schemaOrg` du module sont disponibles dans votre `nuxt.config.ts`. Sans `seo.schema`, la page d'accueil conserve ses nœuds `WebSite` et `WebPage`.

</note>

### **Image de partage social (OG)**

Lorsque vous partagez un lien de votre documentation sur les réseaux sociaux ou certaines plateformes de chat, le lien est **déployé** (unfurled), c'est-à-dire qu'il affiche un aperçu avec un titre, une description et une image. Tout cela est géré par le **protocole Open Graph**.

#### Pages de documentation

Nous utilisons [Nuxt OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction) pour générer automatiquement une image OG pour chaque page de documentation à partir du titre et de la description fournis. Par exemple, l'image OG pour la page actuelle est :

![og image documentation page](https://docus.dev/_og/s/o_9e3c611af9e1d5b2.png)

#### Page d'accueil

Comme pour les pages de documentation, la page d'accueil utilise le même générateur d'image OG basé sur le titre et la description fournis.

![og image landing page](https://docus.dev/_og/s/o_e5724630ae944920.png)

Cependant, si vous souhaitez personnaliser l'image OG de votre page d'accueil, vous pouvez le faire en ajoutant un chemin **absolu** vers une image dans la clé `seo.ogImage` de votre frontmatter.

```md [content/index.md]
---
seo:
  ogImage: '/social-card.png'
---
```

Nous recommandons d'utiliser une image **1280×640** pour un affichage optimal sur les plateformes sociales.

<tip>

Les images OG doivent être servies avec des URLs absolues. Par défaut, l'URL du site est déduite de votre plateforme de déploiement, mais vous pouvez la surcharger en définissant la variable d'environnement `NUXT_SITE_URL`.

</tip>

<tip>

Puisque Docus est un [layer Nuxt](https://nuxt.com/docs/guide/going-further/layers), vous pouvez surcharger les templates OG des pages de documentation ou de la page d'accueil en créant un fichier du même nom dans votre propre répertoire `components/OgImage/`.

```text
components/
  OgImage/
    Docs.takumi.vue     # surcharge l'image OG des pages de documentation
    Landing.takumi.vue  # surcharge l'image OG de la page d'accueil
```

Votre composant reçoit `title`, `description` et `headline` (pages de documentation uniquement) en tant que props et peut utiliser n'importe quel style Tailwind CSS ou inline supporté par le [renderer Takumi](https://nuxtseo.com/docs/og-image/guides/renderers).

</tip>

### Sitemap

Docus génère un sitemap à `/sitemap.xml` avec [`@nuxtjs/sitemap`](https://nuxtseo.com/docs/sitemap), qui liste toutes les pages de contenu. Sur un site multilingue, il devient un index de sitemaps avec un sitemap par locale. Toutes les options `sitemap` du module sont disponibles dans votre `nuxt.config.ts`.

#### Exclure des pages

Pour exclure une page spécifique du sitemap, ajoutez `sitemap: false` à son frontmatter :

```md [content/draft-page.md]
---
sitemap: false
---

Cette page n'apparaîtra pas dans le sitemap.
```

#### URL du site

Pour des URLs de sitemap correctes, définissez la variable d'environnement `NUXT_SITE_URL` :

```bash
NUXT_SITE_URL=https://votre-site.com
```

## En-tête

Configurez le `title` ou le `logo` de votre site de documentation :

```ts [app.config.ts]
export default defineAppConfig({
  header: {
    title: '',
    logo: {
      light: '',
      dark: '',
      alt: '',
    },
  },
})
```

### Brand Assets

Vous pouvez configurer des assets de marque additionnels pour votre logo. Un clic droit sur le logo dans l'en-tête ouvre un menu contextuel avec des actions de copie et de téléchargement.

```ts [app.config.ts]
export default defineAppConfig({
  header: {
    title: 'Mon Projet',
    logo: {
      light: '/logo/logo-dark.svg',
      dark: '/logo/logo-light.svg',
      alt: 'Logo Mon Projet',
      wordmark: {
        light: '/logo/wordmark-dark.svg',
        dark: '/logo/wordmark-light.svg',
      },
      favicon: '/favicon.svg',
      brandAssetsUrl: 'https://example.com/brand',
    },
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Champ
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        logo.wordmark.light
      </code>
      
       / <code>
        dark
      </code>
    </td>
    
    <td>
      Wordmark complet (icône + texte) pour chaque mode couleur.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.display
      </code>
    </td>
    
    <td>
      Variante à afficher dans l'en-tête : <code>
        'logo'
      </code>
      
       (défaut) ou <code>
        'wordmark'
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.class
      </code>
    </td>
    
    <td>
      Classes CSS additionnelles sur l'image du logo (ex. <code>
        'h-8'
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.favicon
      </code>
    </td>
    
    <td>
      Chemin vers le fichier favicon. Par défaut <code>
        /favicon.ico
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logo.brandAssetsUrl
      </code>
    </td>
    
    <td>
      Lien vers votre page de brand assets, affiché dans le menu.
    </td>
  </tr>
</tbody>
</table>

Quand le logo est un SVG, le menu contextuel propose des actions **Copier le logo** et **Copier le wordmark** qui copient le SVG brut avec des fills `currentColor`, prêt à coller dans Figma ou tout outil de design. Pour les formats non-SVG (PNG, etc.), seules les actions de téléchargement sont disponibles.

## Mode couleur

Par défaut, Docus inclut un bouton de changement de mode couleur dans l'en-tête et le pied de page, permettant de basculer entre les modes clair et sombre.

Si votre documentation n'utilise qu'un seul thème, vous pouvez le forcer en définissant l'option `colorMode` :

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    colorMode: 'dark'
  }
})
```

<table>
<thead>
  <tr>
    <th>
      Valeur
    </th>
    
    <th>
      Comportement
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ''
      </code>
      
       (défaut)
    </td>
    
    <td>
      Préférence système avec bouton de bascule
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'light'
      </code>
    </td>
    
    <td>
      Force le mode clair, masque le bouton
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'dark'
      </code>
    </td>
    
    <td>
      Force le mode sombre, masque le bouton
    </td>
  </tr>
</tbody>
</table>

### Raccourci clavier

Appuyez sur <kbd value="D">



</kbd>

 pour basculer entre les modes clair et sombre lorsque le bouton de mode couleur est visible.

Vous pouvez personnaliser ou désactiver ce raccourci dans `app.config.ts` :

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    shortcuts: {
      toggleColorMode: 'd', // Par défaut
    },
  },
})
```

Définissez `toggleColorMode` sur une chaîne vide pour désactiver le raccourci. Consultez la page [Assistant](https://docus.dev/fr/ai/assistant#raccourcis-clavier) pour le format des raccourcis (`meta_d`, `ctrl_shift_p`, etc.).

Lorsqu'un mode couleur est forcé, le bouton de bascule est masqué de l'en-tête et du pied de page, et les commandes de mode couleur sont retirées de la palette de commandes.

## Navigation

### Sous-navigation

Pour les sites de documentation avec de nombreuses sections, vous pouvez activer une sous-navigation qui divise vos dossiers de premier niveau en sections et filtre la barre latérale gauche pour n'afficher que les pages de la section active.

Deux modes d'affichage sont disponibles :

- **header** — affiche une barre d'onglets secondaire sous l'en-tête (desktop uniquement, avec un tiroir sur mobile)
- **aside** — affiche des ancres de section en haut de la barre latérale gauche (avec un tiroir sur mobile)

```ts [app.config.ts]
export default defineAppConfig({
  navigation: {
    sub: 'header', // or 'aside'
  },
})
```

<video src="https://res.cloudinary.com/nuxt/video/upload/v1773263594/docus/subnav_idh2ae.mp4">



</video>

<note>

Les onglets sont automatiquement générés à partir de vos dossiers de premier niveau dans `content/`. Le titre et l'icône de chaque dossier sont lus depuis son fichier `.navigation.yml`

</note>

## Recherche

Docus inclut une recherche plein texte intégrée alimentée par [Nuxt UI ContentSearch](https://ui.nuxt.com/docs/components/content-search). Par défaut, elle utilise le filtrage côté client avec [Fuse.js](https://www.fusejs.io/) qui charge toutes les sections de recherche au démarrage.

### Recherche plein texte FTS5

Vous pouvez passer à [SQLite FTS5](https://content.nuxt.com/docs/utils/use-search-collection) pour une recherche indexée plus rapide avec mise en évidence des extraits intégrée. Cela construit un index FTS5 dans le navigateur via SQLite WASM et n'exécute la recherche que lorsqu'une requête est saisie, au lieu de charger toutes les sections au démarrage.

```ts [app.config.ts]
export default defineAppConfig({
  search: {
    fts: true
  }
})
```

<table>
<thead>
  <tr>
    <th>
      Mode
    </th>
    
    <th>
      Index
    </th>
    
    <th>
      Vitesse
    </th>
    
    <th>
      Tolérance aux fautes
    </th>
    
    <th>
      Chargement initial
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Fuse.js (défaut)
    </td>
    
    <td>
      Scan JS en mémoire
    </td>
    
    <td>
      O(n) par requête
    </td>
    
    <td>
      Fuzzy complet
    </td>
    
    <td>
      Toutes les sections
    </td>
  </tr>
  
  <tr>
    <td>
      FTS5
    </td>
    
    <td>
      Index inversé SQLite
    </td>
    
    <td>
      O(log n)
    </td>
    
    <td>
      Préfixe uniquement
    </td>
    
    <td>
      Aucun
    </td>
  </tr>
</tbody>
</table>

## Liens sociaux

Ajoutez vos liens de réseaux sociaux dans le pied de page en utilisant un `Record<string, string>` où la clé correspond à une icône de la bibliothèque [Simple Icons](https://simpleicons.org/).

```ts [app.config.ts]
export default defineAppConfig({
  socials: {
    x: 'https://x.com/nuxt_js',
    discord: 'https://discord.com/invite/ps2h6QT',
    nuxt: 'https://nuxt.com',
  }
})
```

## Table des matières

Vous pouvez personnaliser la table des matières dans la barre latérale droite de chaque page.

```ts [app.config.ts]
export default defineAppConfig({
  toc: {
    // Renommer le titre de la table des matières
    title: 'Sur cette page',
    // Ajouter une section en bas de la table des matières
    bottom: {
      title: 'Communauté',
      links: [{
        icon: 'i-lucide-book-open',
        label: 'Docs Nuxt UI',
        to: 'https://ui.nuxt.com/getting-started/installation/nuxt',
        target: '_blank'
      }]
    }
  }
})
```

## Locale

Pour une documentation monolingue (sans le module complet `@nuxtjs/i18n`), vous pouvez configurer la locale via `app.config.ts` :

```ts [app.config.ts]
export default defineAppConfig({
  docus: {
    locale: 'fr', // Par défaut : 'en'
  }
})
```

Ceci définit la langue pour :

- Les traductions des composants UI
- Les attributs `lang` et `dir` sur la balise `<html>`
- Les chaînes d'interface intégrées de Docus

<tip to="https://docus.dev/fr/concepts/internationalization">

Pour une documentation multilingue avec changement de langue, consultez le [guide d'internationalisation](https://docus.dev/fr/concepts/internationalization).

</tip>

## Intégration GitHub

Docus lit votre dossier `.git/` pour obtenir l'`url` et la `branch` de votre dépôt afin d'ajouter :

- Icône GitHub dans l'en-tête et le pied de page
- Liens « Modifier cette page » et « Signaler un problème » dans le pied de page de chaque page.

Vous pouvez personnaliser l'`url`, la `branch` et le `rootDir` de votre application docs en ajoutant la configuration suivante à votre fichier `app.config.ts` :

```ts [app.config.ts]
export default defineAppConfig({
  github: {
    url: 'https://github.com/nuxt-content/docus',
    branch: 'main',
    rootDir: 'docs'
  }
})
```

Si vous ne souhaitez pas utiliser GitHub, vous pouvez définir la clé `github` à `false` pour désactiver l'intégration GitHub.

```ts [app.config.ts]
export default defineAppConfig({
  github: false
})
```

<tip to="https://docus.dev/fr/getting-started/studio">

Ces configurations peuvent aussi être gérées dans l'éditeur Studio, essayez-le !

</tip>


## Sitemap

See the full [sitemap](https://docus.dev/sitemap.md) for all pages.