Configuration

Docus vous permet de configurer votre documentation via le fichier app.config.ts fourni par Nuxt.

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.

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: ''
  },
})

export default defineNuxtConfig({
  site: {
    name: 'Docus',
  },
})

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 :

---
seo:
  title: 'Configuration'
  description: 'Personnalisez votre documentation Docus depuis le fichier de configuration Nuxt de l'application.'
---

<!-- Contenu de la page -->

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

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.

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.

---
seo:
  ogImage: '/social-card.png'
---

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

Sitemap

Docus génère automatiquement un sitemap à /sitemap.xml contenant toutes les pages de votre documentation. Cela aide les moteurs de recherche à découvrir et indexer votre contenu.

Exclure des pages

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

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

NUXT_SITE_URL=https://votre-site.com

En-tête

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

export default defineAppConfig({
  header: {
    // Titre à afficher si aucun logo
    title: '',
    // Configuration du logo
    logo: {
      alt: '',
      // Mode clair
      light: '',
      // Mode sombre
      dark: ''
    },
  },
})

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.

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.

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 :

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

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 :

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.

export default defineAppConfig({
  github: false
})