Créer un site statique avec VitePress pour une belle documentation d'aide

Introduction

J'ai toujours été un adepte des générateurs de sites statiques, qui permettent de créer un site web HTML à partir d'un texte (généralement en Markdown) avec un support communautaire. Cela vous permet de passer plus de temps à écrire du contenu qu'à gérer l'infrastructure d'un système de gestion de contenu (CMS) comme WordPress, qui nécessite une base de données et une interface utilisateur frontale pour entrer le contenu. Si je pouvais résumer les trois raisons pour lesquelles j'aime les générateurs de sites statiques, elles seraient les suivantes :

• Performance (les pages sont pré-rendues)

• La possibilité d'avoir des thèmes

• Ils ne nécessitent pas l'exécution d'un code du côté du serveur.

Nous allons nous pencher sur l'un d'entre eux, très populaire, qui s'appelle, VitePress.

vitepressmain.png

Un aperçu de VitePress

VitePress est le petit frère de VuePress et il est alimenté par Vite et Vue.js. Pour ceux qui ne le savent pas, Vite est un outil de construction qui vise à fournir une expérience de développement plus rapide et plus légère pour les projets web modernes, il est donc logique de l'associer à un générateur de site statique tel que VitePress. Vue.js est un framework JavaScript progressif pour la construction d'interfaces utilisateur web. L'un des problèmes initiaux de VuePress était qu'il s'agissait d'une application Webpack, et qu'il fallait beaucoup de temps pour lancer un serveur de développement pour une simple documentation. VitePress résout ces problèmes avec un démarrage quasi instantané du serveur, une compilation à la demande qui ne compile que la page servie, et un HMR rapide comme l'éclair. C'est parti !

Partir de zéro pour créer un site statique fonctionnel

Tout d'abord, créez un dossier dans lequel vous développerez votre site statique.

Ensuite, il faut l'initialiser avec Fil ou NPM. Pour cet exemple, nous utiliserons Yarn. Si vous n'avez pas installé Yarn, vous pouvez l'installer sur la page de page des téléchargements. Pour ceux qui utilisent NPM, la documentation de VitePress se trouve ici.

Une série de questions vous sera posée, et vous pouvez soit remplir les détails ici, soit les laisser en blanc, comme je l'ai fait.

yarn init
yarn init v1.22.19
question name (static-starter):
question version (1.0.0):
question description:
question entry point (index.js):
question repository url:
question author:
question license (MIT):
question private:
success Saved package.json
Done in 26.93s.

Note : Vous pourrez toujours les compléter ultérieurement lors de la configuration du site.

À ce stade, vous n'aurez qu'un seul fichier package.json unique. Vous devez maintenant ajouter VitePress et Vue comme dépendances pour le projet.

yarn add --dev vitepress vue

Nous avons maintenant besoin d'un endroit pour stocker les documents que nous allons créer et ajouter un exemple de document.

mkdir docs 
cd docs
touch index.md

Modifiez le contenu de index.md pour y inclure le texte suivant :

# Hello VitePress.

Vous devriez maintenant avoir les fichiers et dossiers suivants :

docs 
├── index.md
node_modules 
package.json 
yarn.lock

Nous devons ajouter la section suivante scripts à notre fichier package.json.

{
  "name": "static-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vitepress": "^1.0.0-alpha.21",
    "vue": "^3.2.41"
  },
    "scripts": {
      "docs:dev": "vitepress dev docs",
      "docs:build": "vitepress build docs",
      "docs:serve": "vitepress serve docs"
  }
}

Cela nous permettra d'avoir différents profils en fonction de la situation.

Vous pouvez déployer le serveur en exécutant yarn docs:dev comme indiqué ci-dessous.

yarn docs:dev
yarn run v1.22.19
$ vitepress dev docs
vitepress v1.0.0-alpha.21

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

VitePress prend en charge le "rechargement à chaud", ce qui signifie qu'après avoir enregistré un fichier dans le projet, vous n'aurez pas à reconstruire le site pour voir vos modifications.

Vous devriez maintenant avoir un serveur qui tourne, et il tourne généralement à l'emplacement suivant : http://localhost:5173.

helloworld.gif

Félicitations ! Notre application fonctionne maintenant, et vous pouvez déjà remarquer certaines des caractéristiques et des fonctionnalités que nous avons reçues en utilisant VitePress, comme par exemple :

• Site réactif avec animations

• Construire en appliquant la philosophie "Mobile-first

• Mode sombre et lumineux intégré

Ajouter des pages et comprendre la structure des fichiers

Ajoutons une autre page vers laquelle l'utilisateur final peut naviguer une fois le site chargé. Tout d'abord, créez un fichier nommé another-page.md dans le dossier docs dans le dossier Ajoutez le texte suivant au contenu du fichier # Another Page.

Votre dossier docs devrait ressembler à ceci.

docs
├── index.md
├── another-page.md

Vous ne le trouverez pas si vous essayez de naviguer vers another page.md dans votre navigateur web. Vous pouvez accéder à la page manuellement en suivant l'URL : http://localhost:5173/another-page.

Note : Remarquez que la structure du répertoire correspond au chemin d'accès à l'URL.

Comment remédier à cette situation ?

Ajout de la navigation

Nous avons les bases d'un site web, mais il manque des capacités de navigation pour trouver les autres pages. Le menu latéral est généralement utilisé pour les sites de documentation. Pour l'ajouter, nous devons d'abord procéder à quelques vérifications.

Pour personnaliser et ajouter de la navigation à votre site, nous allons d'abord créer un répertoire .vitepress à l'intérieur de votre répertoire docs répertoire. Une fois terminé, ajoutez un autre fichier appelé config.js. C'est dans ce dossier que seront placés tous les fichiers de configuration spécifiques à VitePress. La structure de votre projet devrait ressembler à ce qui suit :

docs
├── index.md
├── another-page.md
└── .vitepress
    └── config.js

Ouvrez votre vitepress/config.js et ajoutez le code ci-dessous :

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.'
}

Cela fournira un titre et une description par défaut pour le site, que les moteurs de recherche indexeront.

Ensuite, nous allons configurer notre barre de navigation de haut niveau pour qu'elle contienne deux éléments supplémentaires pour notre feuille de route et des moyens pour nos utilisateurs de Retour d'information. Ajoutez ce qui suit à votre fichier vitepress/config.js après le champ description après le champ

themeConfig: {
 nav: [
  { text: 'Roadmap', link: '/roadmap' },
  { text: 'Feedback', link: '/feedback' }
]

toplevelnavigation.png

Super ! Notre site prend forme ! Maintenant, ajoutons notre barre latérale sous l'élément nav que nous venons de créer.

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.',
  themeConfig: {
    nav: [
      { text: 'Roadmap', link: '/roadmap' },
      { text: 'Feedback', link: '/feedback' }
    ],
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
        ]
      }
    ]
  }
}

Notre site commence à prendre forme ! Nous avons ajouté un niveau supérieur et une barre de navigation latérale. Nous avons également une Page suivante qui permet d'accéder à la page Introduction (une fois que nous l'aurons créée).

sidelevelnavigation.png

Ajoutons toutes les pages que nous venons de créer :

Créez les fichiers suivants appelés roadmap.md, feedback.md, introduction.md et getting-started.md dans le dossier docs et donnez-leur un en-tête du même nom.

Par exemple, # Roadmap serait saisi dans le fichier roadmap.md à l'intérieur du fichier. Procédez de la même manière pour tous les fichiers.

Une fois que tout a été sauvegardé, retournez sur votre site pour vérifier que tous les liens fonctionnent maintenant comme prévu.

navigationadded.gif

Autres caractéristiques notables

Liens d'édition GitHub ou GitLab

Vous pouvez créer automatiquement un lien sur chaque page pour permettre à vos lecteurs de contribuer à l'exactitude de la page par le biais de services de gestion Git tels que GitHub ou GitLab. Pour l'activer, ajoutez themeConfig.editLink à votre configuration comme indiqué ci-dessous :

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

Désormais, chaque page rendue aura un lien vers GitHub (ou GitLab) pour que l'utilisateur puisse effectuer une demande d'extraction.

editpage.png

Conteneurs sur mesure

La prise en charge des conteneurs personnalisés est intégrée lorsque vous souhaitez attirer l'attention du lecteur sur quelque chose, par exemple une info, un conseil, un avertissement, etc.

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Cela se traduit par :

tipbox.png

Mise en évidence de la syntaxe dans les blocs de code

La mise en évidence de la syntaxe dans les blocs de code est prise en charge de différentes manières. Cet exemple montre comment vous pouvez mettre en évidence une ligne dans un bloc de code :

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

syntaxhighlighting.png

Déployer votre application

Maintenant que nous avons développé notre site statique et que nous y avons ajouté des pages ainsi qu'une barre de navigation riche, déployons notre application. Vous pouvez le faire en exécutant la commande suivante yarn docs:build.

Si tout fonctionne correctement, vous verrez ce qui suit :

yarn docs:build
yarn run v1.22.19
$ vitepress build docs
vitepress v1.0.0-alpha.21
✓ building client + server bundles...
⠋ rendering pages...(node:3164) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
✓ rendering pages...
build complete in 8.29s.
Done in 8.97s.

Les fichiers rendus seront placés par défaut sur la page de votre projet sous dist. Par exemple, mes fichiers ont été rendus ici : C:\Users\mbcru\source\static-starter\docs\.vitepress\dist

fileexplorer.png

Synthèse

Maintenant que votre site statique est opérationnel, vous pouvez ajouter des fonctions de communication spécifiques, telles que Vonage comme la fonction Videoou messagerieetc.

Si vous avez des questions ou des commentaires, rejoignez-nous sur le Slack des développeurs de Vonage ou envoyez-moi un Tweet sur Twitteret je vous répondrai. Merci encore d'avoir lu, et je vous donne rendez-vous au prochain numéro !