Comment créer un site web de documentation avec VuePress

Une introduction à VuePress et à son utilisation

Figure 1: Photo de Clément H sur Unsplash

Créer un site Web de documentation pour votre projet le plus récent peut être décourageant et prendre beaucoup de temps. Le plus souvent, vous souhaitez simplement avoir un site Web prêt à être utilisé afin que d'autres personnes puissent consulter et / ou utiliser votre projet.

VuePress facilite la création de sites Web de documentation sans écrire beaucoup de code.

Qu'est-ce que VuePress?

VuePress est un générateur de site statique basé sur Vue qui génère des pages HTML à partir de fichiers de démarquage. Celles-ci vous permettent de vous concentrer sur la rédaction de la documentation au lieu de perfectionner votre site Web.

Dans VuePress, chaque page possède son propre code HTML statique prédéfini, ce qui lui confère d'excellentes performances de chargement et une convivialité vraiment SEO (Search Engine Optimization).

Il fournit également un thème par défaut qui peut relancer votre processus de développement en vous fournissant un joli thème prêt à l'emploi. Celles-ci sont également utilisées pour le site Web officiel de la documentation VuePress.

Installer VuePress et créer un projet

Installer VuePress et créer un projet ou ajouter VuePress à un projet existant est très simple. Vous pouvez installer VuePress en utilisant NPM:

npm install -g vuepress

ou en utilisant du fil:

filé global ajouter vuepress

Vous pouvez également ajouter VuePress à un projet existant. À cette fin, je recommande l'utilisation de fil, car si le projet utilise Webpack 3.x en tant que dépendance, Npm ne peut pas générer l'arbre de dépendance correct.

Pour ajouter VuePress à un projet existant, utilisez:

fil add -D vuepress

Lancer le projet

Pour exécuter un projet, ouvrez une ligne de commande, allez dans votre répertoire de travail et tapez vuepress dev pour démarrer le serveur de développement.

Au début, nous aurons une erreur 404 en disant qu’il n’ya rien ici. C’est parce que nous n’avons encore créé aucun fichier de démarquage. Nous allons donc utiliser rapidement la ligne de commande pour créer notre premier fichier de démarquage:

echo '# Hello VuePress'> LISEZMOI.md

Après avoir tapé ceci, vous verrez la page s'actualiser, vous montrant une barre de recherche ainsi que le texte que nous avons spécifié dans la commande echo. VuePress permet aux utilisateurs de rechercher automatiquement toutes les balises h2 et h3 contenues dans le site Web.

Vous pouvez voir une image de la page ci-dessous:

Figure 2: Démarrer le site VuePress

Ajout d'un fichier de configuration

Sans configuration, la page n'offre pas beaucoup de fonctionnalités et l'utilisateur n'a aucun moyen de naviguer sur le site. Pour ajouter des configurations personnalisées, nous devons créer un fichier config.js que nous devons placer dans un dossier .vuepress, qui contiendra tous les fichiers spécifiques à VuePress.

Donc, notre nouvelle structure de projet ressemblera à ceci:

| - Projet
   | - LISEZMOI.md
   | - .vuepress
      | - config.js

Nous allons maintenant créer un objet Javascript que nous pourrons utiliser pour spécifier nos configurations. Dans ce document, nous spécifierons un titre et une description:

module.exports = {

 titre: 'Hello VuePress',

 description: 'Je joue juste'
}

Si vous regardez le site Web maintenant, vous devriez voir qu'il a un en-tête avec un titre. Si vous inspectez le site Web à l'aide des outils de développement, vous devriez voir une balise meta description dans l'en-tête.

Thème par défaut

Comme mentionné au début de l'article, VuePress est livré avec un thème par défaut pour des éléments tels que la page d'accueil, la barre de navigation, la barre latérale et bien d'autres.

Le thème par défaut a un aspect de site de documentation classique (du moins pour moi) et est très utile pour fournir un point de départ au style de votre site Web.

Vous pouvez obtenir le thème par défaut dans la documentation de VuePress.

Pour le style de la page d’accueil, l’avant-plan YAML est utilisé et la seule chose à faire est de le copier-coller dans notre fichier README.md racine.

Alors maintenant, notre fichier README.md racine ressemble à quelque chose comme:

---
accueil: vrai
heroImage: https://vuepress.vuejs.org/hero.png
actionText: Commencer →
actionLink: / guide /
fonctionnalités:
- titre: Simplicity First
 détails: Une configuration minimale avec une structure de projet centrée sur le démarquage vous aide à vous concentrer sur l'écriture.
- titre: Vue-Powered
 Détails: Profitez de l'expérience de développement de Vue + webpack, utilisez les composants Vue dans Markdown et développez des thèmes personnalisés avec Vue.
- titre: performant
 détails: VuePress génère du code HTML statique pré-rendu pour chaque page et s’exécute en tant que SPA une fois la page chargée.
footer: Licence MIT | Copyright © 2018-présent Evan You
---
'# Bonjour VuePress'

Vous pouvez voir le nouveau design de la page d'accueil dans l'image ci-dessous:

Figure 3: Conception de la page d'accueil par défaut

Créer une barre de navigation

VuePress vous permet d'ajouter une barre de navigation en spécifiant un objet themeConfig dans le fichier config.js et en lui transmettant un tableau d'objets de navigation.

Comme dans la documentation officielle, nous ajouterons un lien vers une page de guide, qui n’a pas encore été créée, ainsi qu’un lien vers google.com.

module.exports = {
   titre: 'Hello VuePress',
   description: 'Je joue juste',
   themeConfig: {
       nav: [
         {text: 'Home', lien: '/'},
         {texte: 'Guide', lien: '/ guide /'},
         {texte: 'externe', lien: 'https://google.com'},
       ]
   }
}
Figure 4: barre de navigation

Créer des itinéraires

Maintenant que nous avons une barre de navigation qui nous permet de naviguer entre différentes pages, nous devons créer la page de guidage.

VuePress implémente un système de routage facile à utiliser. Pour le / guide / route, il recherche un fichier README.md dans un répertoire guide.

Après avoir créé le répertoire et le fichier, notre structure de projet se présente comme suit:

| - Projet
   | - LISEZMOI.md
   | - .vuepress
      | - config.js
   | - guide
      | - LISEZMOI.md

En tant que contenu du fichier README.md, nous allons simplement entrer quelques titres et lorem ipsum text.

# Guider
Lorem ipsum dolor sit amet, consectetur elit adipiscing, sed eiusmod tempor incidid ut labore et dolore magna aliqua. Tout en minimisant les effets, l’exercice de nos exercices en cours d’expérience, il n’existe que d’excellents résultats. Duis aute irure dolor in reprrehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
## C'est génial
Lorem ipsum dolor sit amet, consectetur elit adipiscing, sed eiusmod tempor incidid ut labore et dolore magna aliqua. Tout en minimisant les effets, l’exercice de nos exercices en cours d’expérience, il n’existe que d’excellents résultats. Duis aute irure dolor in reprrehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Maintenant, si nous naviguons sur la page du guide, nous voyons:

Figure 5: page de guide

Créer une barre latérale

La plupart des sites Web de documentation proposent une barre latérale facilitant la navigation entre les différentes sections d’un même côté.

Le moyen le plus simple de créer une telle barre latérale consiste à spécifier la barre latérale: "auto" dans notre themeConfig.

Code:

module.exports = {
   titre: 'Hello VuePress',
   description: 'Je joue juste',
   themeConfig: {
       nav: [
         {text: 'Home', lien: '/'},
         {texte: 'Guide', lien: '/ guide /'},
         {texte: 'externe', lien: 'https://google.com'},
       ],
       encadré: 'auto'
   }
}

Cela génère une barre latérale:

Figure 6: Barre latérale automatique

C’est génial dans notre cas d’utilisation mais cela ne fonctionne pas bien si vous avez des fichiers de balisage supplémentaires. Dans ce cas, vous devez spécifier un objet de barre latérale contenant des tableaux pour chaque page «principale».

Pour cet exemple, je vais créer un autre fichier de démarques appelé «Plus Informations.md», qui est également placé dans le répertoire du guide.

Le fichier ne contient que du texte:

# Plus d'informations
Plus d'informations sur notre projet génial

Si vous regardez à nouveau la barre latérale, vous voyez que rien n'a changé. Le réglage automatique ne fonctionne donc pas pour les fichiers de démarquage supplémentaires. Pour cela, nous devons changer notre code dans la barre latérale comme suit:

module.exports = {
   titre: 'Hello VuePress',
   description: 'Je joue juste',
   themeConfig: {
       nav: [
         {text: 'Home', lien: '/'},
         {texte: 'Guide', lien: '/ guide /'},
         {texte: 'externe', lien: 'https://google.com'},
       ],
       sidebar: {
           '/guider/': [
               '',
               'Plus d'informations'
           ]
       }
   }
}

Comme vous pouvez le constater, nous avons ajouté un tableau de liens dans la barre latérale pour le guide / itinéraire afin que nous puissions accéder à la page d'informations supplémentaires.

Figure 7: Barre latérale personnalisée

Conclusion

VuePress est un outil pratique pour créer des sites Web de documentation sans écrire beaucoup de code. Il dispose de nombreuses fonctionnalités qui facilitent la création d’une expérience utilisateur exceptionnelle.

Je ne pouvais couvrir qu'une quantité très minime de fonctionnalités dans ce post. Si vous souhaitez en savoir plus sur VuePress et ses fonctionnalités, consultez la documentation officielle et laissez un commentaire ci-dessous si vous souhaitez un autre article concernant VuePress.

Si vous avez aimé cet article, envisagez de vous abonner à ma chaîne Youtube et de me suivre sur les réseaux sociaux.

Le code couvert dans cet article est disponible en tant que référentiel Github.

Si vous avez des questions ou des critiques, vous pouvez être contacté via Twitter ou la section commentaires.