Cours 16 - Documentation avec Vitepress

Objectifs

• Comprendre l'intérêt et les principes de base de VitePress.
• Savoir mettre en place un projet de documentation avec VitePress.
• Être capable de personnaliser et de déployer une documentation VitePress.

Déroulement

• Introduction au cours
• Atelier 16 - Création d'une documentation avec VitePress
• Exercice 16 - Revue de code documentée
• Conclusion

Introduction à VitePress

• VitePress est un générateur de sites statiques conçu par l'équipe de Vue.js.
• Il s'appuie sur Vite, l'outil de build moderne et performant.
• VitePress vise à fournir une expérience de documentation rapide et agréable, tant pour les créateurs de contenu que pour les lecteurs.
• Il combine la meilleure partie de Vue.js et de Vite, offrant des fonctionnalités telles que le rechargement à chaud, une configuration minimale et une performance optimisée pour les projets de documentation.

Pourquoi choisir VitePress ?

1. Performance: Grâce à Vite, VitePress offre des temps de chargement rapides et un rechargement à chaud ultra-rapide pendant le développement.
2. Facilité d'utilisation: Avec une configuration minimaliste, il est facile de démarrer avec VitePress. La création et la gestion de votre documentation deviennent un jeu d'enfant.
3. Flexibilité: VitePress est hautement personnalisable. Vous pouvez facilement ajuster le thème, la mise en page ou ajouter des fonctionnalités via des plugins.
4. Intégration de Vue.js: Écrivez vos exemples de code et vos démos directement en Vue.js, permettant une intégration transparente avec les projets Vue.js.

Un peu de Markdown

Markdown est un langage de balisage léger conçu pour être facile à écrire et à lire. Il vous permet de formater du texte sur le web de manière simple.
Titres
Markdown utilise les symboles # pour les titres. Le nombre de # avant le titre représente le niveau du titre :

# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4

Paragraphe
Les paragraphes en Markdown sont simplement des lignes de texte suivies d'une ou plusieurs lignes vides.

Voici un paragraphe. Il suffit d'écrire votre texte normalement.

Italique et Gras
Pour mettre du texte en italique, entourez-le avec un astérisque * ou un tiret bas _. Pour le gras, utilisez deux astérisques ** ou deux tirets bas __.

*texte en italique*
_texte en italique aussi_

**texte en gras**
__texte en gras aussi__

Liens
Pour créer un lien, entourez le texte du lien avec des crochets [] et immédiatement après, mettez l'URL du lien entre parenthèses ().

[Documentation Markdown](https://www.markdownguide.org/)

Il y a beaucoup d'autres possibilités (images, tableaux, listes, codes, etc.), mais il faut consulter la documentation!

Atelier 16 - Création d'une documentation avec VitePress

Prérequis

Avant de commencer, assurez-vous d'avoir Node.js (version 12.x ou supérieure) installé sur votre machine.

• J'espère que vous l'avez encore ;P

Vidéo de présentation

Learn How to Write Beautiful Documentation with Vitepress

À lire et consulter

• Documentation officielle de Vitepress
• Documentation Markdown

Une nouvelle extension de VS Code à installer

• Nom : Markdown Editor
• ID : zaaack.markdown-editor
• Description : A full-featured WYSIWYG editor for markdown.
• Version : 0.1.10
• Serveur de publication : zaaack
• Lien de la Place de marché pour VS : https://marketplace.visualstudio.com/items?itemName=zaaack.markdown-editor

Installation de Vitepress

Pour installer Vitepress, consulter le guide:
https://vitepress.dev/guide/getting-started#setup-wizard

• Créer un dossier atel16
• Aller dans le terminal à partir du dossier atel16

Commande NPX

npm add -D vitepress
npx vitepress init

Questions à répondre:

• Faites la création d'une nouvelle documentation avec Vitepress:
  ◇ Where should VitePress initialize the config?
  │ ./
  ◇ Site title:
  │ Atelier 16
  ◇ Site description:
  │ Atelier sur l'installation et l'utilisation de Vitepress
  ◆ Theme:
  │ ● Default Theme (Out of the box, good-looking docs)
  │
  ◇ Use TypeScript for config and theme files?
  │ Yes
  │
  ◇ Add VitePress npm scripts to package.json?
  │ Yes
  │
  └ Done! Now run npm run docs:dev and start writing.

Ensuite, faire les commandes proposées à l'écran

Voilà une nouvelle manière de faire de la documentation en ligne avec un site web complet!

NOTE: Si vous voulez ajouter de la documentation à un projet existant vous douvez changer la ligne suivante:
◇ Where should VitePress initialize the config?
│ ./docs

docs sera donc votre dossier de documentation à l'intérieur de votre projet existant!

Utilisation de Vitepress

Maintenant, on va utiliser le mastodonte :P
Si vous avez bien installé l'extension proposée, vous pourrez modifier les fichiers markdown (extension .md).

• Ouvrez le fichier index.md
• Faire clic droit sur le nom index.md dans l'onglet de l'éditeurs et open with markdown editor
• Aller voir aussi les deux autres fichiers md
• Vous pouvez faire quelques tests et voir comment ça se comporte à l'affichage

Personnalisation de votre documentation

VitePress permet de personnaliser l'apparence et le comportement de votre documentation via le fichier de configuration .vitepress/config.mts dans votre dossier racine.

Exemple de configuration basique :

  title: 'Ma Documentation',
  description: 'La documentation de mon projet',

Déployer votre documentation

Pour déployer votre documentation, commencez par construire votre site avec la commande npm run docs:build. Cela générera un dossier dist dans votre dossier docs/.vitepress, que vous pourrez déployer sur des plateformes comme Netlify, Vercel, ou GitHub Pages.

• Dans le cadre du cours, nous allons utiliser GitHub Page!
• Vous n'avez pas à déployer votre documentation dans cet atelier.

Exercice 16

Exercice 16 - Revue de code documentée