Thèmes de documentation v0.8.1

Créez une belle documentation comme ce site Web en quelques secondes ✨

Découvrez l'exemple en direct

Pour commencer

Pour commencer rapidement, vous pouvez utiliser le package create-nuxt-content-docs.

yarn create nuxt-content-docs <project-name>
# Assurez-vous que npx est installé (npx est livré par défaut depuis NPM 5.2.0) ou npm v6.1 ou yarn.
npx create-nuxt-content-docs <project-name>
# À partir de npm v6.1, vous pouvez faire :
npm init nuxt-content-docs <project-name>

Il vous posera quelques questions (nom, titre, url, référentiel, etc.), une fois répondu, les dépendances seront installées. L'étape suivante consiste à accéder au dossier du projet et à le lancer:

cd <project-name>
yarn dev
cd <project-name>
npm run dev

L'application s'exécute maintenant sur http://localhost:3000. Bien joué !

Configuration manuelle

Disons que nous créons la documentation d'un projet open-source dans le répertoire docs/.

Le thème est une application NuxtJS classique, vous avez besoin de :

package.json

Ce fichier peut être créé avec npm init.

Installez nuxt et @nuxt/content-theme-docs:

yarn add nuxt @nuxt/content-theme-docs
npm install nuxt @nuxt/content-theme-docs

Exemple

package.json
{
  "name": "docs",
  "version": "1.0.0",
  "scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "start": "nuxt start",
    "generate": "nuxt generate"
  },
  "dependencies": {
    "@nuxt/content-theme-docs": "^0.1.3",
    "nuxt": "^2.14.0"
  }
}

nuxt.config.js

Importez la fonction de thème depuis @nuxt/content-theme-docs:

nuxt.config.js
import theme from '@nuxt/content-theme-docs'

export default theme({
  // [additional nuxt configuration]
})

Le thème exporte une fonction pour configurer nuxt.config.js et vous permet d'ajouter / remplacer la configuration par défaut.

Consultez la documentation de defu.arrayFn pour voir comment la configuration est fusionnée.

Exemple

nuxt.config.js
import theme from '@nuxt/content-theme-docs'

export default theme({
  docs: {
    primaryColor: '#E24F55'
  },
  loading: { color: '#00CD81' },
  i18n: {
    locales: () => [{
      code: 'fr',
      iso: 'fr-FR',
      file: 'fr-FR.js',
      name: 'Français'
    }, {
      code: 'en',
      iso: 'en-US',
      file: 'en-US.js',
      name: 'English'
    }],
    defaultLocale: 'en'
  },
  buildModules: [
    ['@nuxtjs/google-analytics', {
      id: 'UA-12301-2'
    }]
  ]
})

N'oubliez pas d'installer les dépendances des modules que vous ajoutez dans votre nuxt.config.js.

tailwind.config.js

v0.4.0+

Vous pouvez remplacer la configuration du thème par défaut en créant le votre dans tailwind.config.js.

La conception du thème est basé sur la couleur primary pour faciliter le remplacement.

Les couleurs par défaut sont générées en utilisant theme-colors avec docs.primaryColor comme base. v0.7.0+

Exemple

tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          // ...
        }
      }
    }
  }
}

content/

C'est ici que vous placez vos fichiers de contenu markdown. Vous pouvez en savoir plus dans la section suivante.

static/

C'est ici que vous placez vos fichiers statiques comme le logo.

Vous pouvez ajouter un fichier static/icon.png pour activer nuxt-pwa et générer un favicon automatiquement.

L'icône doit être un carré d'au moins 512x512px

Vous pouvez ajouter un fichier static/preview.png pour avoir une image de prévisualisation dans vos métas.

L'image doit être au moins 640×320px (1280×640px pour un meilleur affichage).

Exemple

content/
  en/
    index.md
static/
  icon.png
nuxt.config.js
package.json

Contenu

Une fois que vous avez configuré votre documentation, vous pouvez directement commencer à écrire votre contenu.

Consultez la documentation sur l'écriture de contenu markdown

Langues

Le premier niveau de répertoires dans le dossier content/ correspond aux paramètres de langues utilisés avec nuxt-i18n défini dans votre nuxt.config.js. Par défaut, seuls les paramètres de langues par défaut en sont définis, vous devez créer un répertoire content/en/ pour le faire fonctionner.

Vous pouvez remplacer les paramètres de langues dans votre nuxt.config.js:

nuxt.config.js
import theme from '@nuxt/content-theme-docs'

export default theme({
  i18n: {
    locales: () => [{
      code: 'fr',
      iso: 'fr-FR',
      file: 'fr-FR.js',
      name: 'Français'
    }, {
      code: 'en',
      iso: 'en-US',
      file: 'en-US.js',
      name: 'English'
    }],
    defaultLocale: 'en'
  }
})

Comme expliqué dans la section nuxt.config.js, nous utilisons defu.arrayFn pour fusionner votre configuration. Vous pouvez remplacer le tableau i18n.locales en utilisant une fonction, ou vous pouvez passer un tableau à concaténer avec celui par défaut (qui n'a que le paramètre de langue en).

Routes

Chaque page markdown dans le répertoire content/{locale}/ deviendra une page et sera répertoriée dans la navigation de gauche.

Vous pouvez également placer vos fichiers markdown dans des sous-répertoires pour générer des sous-routes. v0.4.+

Exemple

content/
  en/
    Exemples/
      basic-usage.md
    setup.md

Result

/Exemples/basic-usage
/setup

Vous pouvez jeter un oeil à notre dossier de contenu docs pour avoir un exemple

Front-matter

Pour le faire fonctionner correctement, assurez-vous d'inclure ces propriétés dans la section front-matter de vos fichiers markdown.

Champs obligatoires

  • title (String)
    • Le titre de la page sera injecté dans les métas
  • description (String)
    • La description de la page sera injecté dans les métas
  • position (Number)
    • Ceci sera utilisé pour définir l'ordre des pages dans la navigation

Champs facultatifs

  • category (String)
    • Ceci sera utilisé pour regrouper les pages dans la navigation
  • version (Float)
    • Alertez les utilisateurs que la page est nouvelle avec un badge. Une fois la page vue, la version est stockée dans le stockage local jusqu'à ce que vous l'incrémentiez
  • fullscreen (Boolean)
    • Agrandit la page et masque la table des matières
  • menuTitle (String) v0.4.0+
    • Remplace le titre de la page qui sera affiché dans le menu de gauche (par défaut titre)
  • subtitle (String) v0.5.0+
    • Ajoute un sous-titre sous le titre de la page
  • badge (String) v0.5.0+
    • Ajoute un badge à côté du titre de la page

Exemple

content/en/index.md
---
title: 'Introduction'
description: 'Empower your NuxtJS application with this awesome module.'
position: 1
category: 'Getting started'
version: 1.4
fullscreen: false
menuTitle: 'Intro'
---

Introducing my awesome Nuxt module!

Réglages

Vous pouvez créer un fichier content/settings.json pour configurer le thème.

Propriétés

  • title (String)
    • Le titre de votre documentation
  • url (String)
    • L'url où votre documentation sera déployée
  • logo (String | Object)
    • Le logo de votre projet, peut-être un Objet pour définir un logo par color mode
  • github (String)
    • Le repository GitHub de votre projet owner/name pour afficher la dernière version, la page des versions, le lien en haut et le Editer cette page sur GitHub sur chaque page. Exemple: nuxt/content.
    • Pour GitHub Enterprise, vous devez attribuer une URL complète de votre projet sans barre oblique finale. Exemple: https://hostname/repos/owner/name. v0.6.0+
  • githubApi (String) v0.6.0+
    • Pour GitHub Enterprise, en plus de github, vous devez attribuer une URL complète d'API de votre projet sans barre oblique finale. Exemple: https://hostname/api/v3/repos/owner/name.
    • Les versions sont extraites de ${githubApi}/releases.
  • twitter (String)
    • Le nom d'utilisateur Twitter @username que vous souhaitez lier. Exemple: @nuxt_js
  • defaultBranch (String) v0.2.0+
    • La branche par défaut du repository GitHub de votre projet, utilisée dans le lien Editer cette page sur GitHub sur chaque page (par défaut main s'il ne peut pas être détecté).
  • defaultDir (String) v0.6.0+
    • The default dir of your project, used in the Editer cette page sur GitHub on each page (defaults to docs. Can be an empty string eg. "").
    • Le répertoire par défaut de votre projet, utilisé dans Editer cette page sur GitHub sur chaque page (par défaut docs. Peut être une chaîne vide, par exemple. "").
  • layout (String) v0.4.0+
    • La mise en page de votre documentation (par défaut, default). Peut être changé en single pour avoir un document d'une seule page.
  • algolia (Object) v0.7.0+
    • Cette option vous permet d'utiliser Algolia DocSearch pour remplacer la recherche intégrée simple. Pour l'activer, vous devez fournir au moins le apiKey et le indexName :
      "algolia": {
          "apiKey": "<API_KEY>",
          "indexName": "<INDEX_NAME>",
          "langAttribute": "language"
      }
      
    • Si vous utilisez i18n, assurez-vous que <langAttribute> est le même que le sélecteur de langue html dans la configuration (par défaut, language).
    • Jetez un oeil sur @nuxt/content pour la configuration de docsearch comme exemple.

Exemple

content/settings.json
{
  "title": "Nuxt Content",
  "url": "https://content.nuxtjs.org",
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  },
  "github": "nuxt/content",
  "twitter": "@nuxt_js"
}

Images

Vous pouvez appliquer les classes dark-img et light-img à vos images lorsque vous avez deux versions à permuter automatiquement en fonction du mode couleur.

Exemple

<img src="/logo-light.svg" class="light-img" alt="Logo light" />
<img src="/logo-dark.svg" class="dark-img" alt="Logo dark" />

Result

Logo light Logo dark

Essayez de basculer entre le mode clair et sombre : 

Composants

Le thème est livré avec des composants Vue.js par défaut que vous pouvez utiliser directement dans votre contenu markdown.

Vous pouvez créer vos propres composants dans le dossier components/global/, consultez cette section. v0.3.0+

<alert>

Props

  • type
    • Type: String
    • Défaut: 'info'
    • Valeurs: ['info', 'success', 'warning', 'danger']

Exemple

<alert>

Check out an info alert with a `codeblock` and a [link](/themes/docs)!

</alert>

Result

Check out an info alert with a codeblock and a link!

<list>

Props

  • items
    • Type: Array
    • Défaut: []
  • type v0.7.0+
    • Type: String
    • Défaut: 'primary'
    • Valeurs: ['primary', 'info', 'success', 'warning', 'danger']
  • icon v0.7.0+
    • Type: String
    • Peut être utilisé pour remplacer l'icône par défaut type, consultez les icônes disponibles

Exemple

---
items:
  - Item1
  - Item2
  - Item3
---

<list :items="items"></list>

Result

Item1
Item2
Item3

<badge>

v0.5.0+

Exemple

<badge>v1.2+</badge>

Result

v1.2+

<code-group>

Ce composant utilise des slots, reportez-vous au code-block ci-dessous.

<code-block>

Props

  • label
    • Type: String
    • required
  • active
    • Type: Boolean
    • Défaut: false

Exemple

# Backslashes are for demonstration

<code-group>
  <code-block label="Yarn" active>

  ```bash
  yarn add @nuxt/content-theme-docs
  \```

  </code-block>
  <code-block label="NPM">

  ```bash
  npm install @nuxt/content-theme-docs
  \```

  </code-block>
</code-group>

Result

yarn add @nuxt/content-theme-docs
npm install @nuxt/content-theme-docs

<code-sandbox>

Props

  • src
    • Type: String
    • required

Exemple

---
link: https://codesandbox.io/embed/nuxt-content-l164h?hidenavigation=1&theme=dark
---

<code-sandbox :src="link"></code-sandbox>

Result

Loading CodeSandbox...

Showcases

Editer cette page sur GitHub Mise à jour le Tue, March 2, 2021