Initialisation du Projet

Avant de commencer à créer notre blog, il est essentiel de comprendre ce qu'est VitePress et ses origines. La familiarité avec les outils que nous utilisons pour la création de notre blog est cruciale.

VitePress ​

Selon la page d'accueil :

Générateur de Sites Statique alimenté par Vite & Vue, de Markdown à de Belles Documentations en Quelques Minutes

Bien que l'utilisation de "documentations" dans le slogan puisse suggérer que VitePress est exclusivement réservé aux sites de documentation, il peut créer tout site centré sur le contenu. Cet accent est un mouvement marketing stratégique.

La section "Qu'est-ce que VitePress ?" explique :

VitePress est un générateur de sites statiques (SSG) conçu pour construire des sites web rapides et centrés sur le contenu. En bref, VitePress prend votre contenu source écrit en Markdown, lui applique un thème, et génère des pages HTML statiques qui peuvent être facilement déployées n'importe où.

En essence, VitePress s'appuie sur une application de base Vite et Vue, similaire à ce que vous pourriez générer avec npx create-vite --template vue. Cependant, VitePress offre bien plus.

Il introduit trois fonctionnalités clés à l'application standard Vite et Vue :

1. Support Markdown : VitePress est livré avec un compilateur Markdown vers HTML préconfiguré basé sur markdown-it. Il prend en charge nativement le frontmatter, la coloration syntaxique, les alertes de GitHub, les émoji, les composants Vue, et plus. Il s'appuie sur une configuration complète avec de nombreux plugins. Vous pouvez consulter le code source pour plus de détails.
2. Chargement de Données : VitePress permet le chargement de données depuis le système de fichiers, les réseaux, ou toute autre source. Cette fonctionnalité puissante facilite la création de sites web dynamiques en utilisant un générateur de sites statiques. Plus de détails sont disponibles dans la section Chargement de Données de la documentation.
3. Pré-rendu au moment de la Construction : VitePress fonctionne comme une application à page unique (SPA), améliorant l'expérience utilisateur (UX) mais posant des défis en matière d'optimisation pour les moteurs de recherche (SEO). Cependant, en raison de sa nature statique et centrée sur le Markdown, VitePress pré-rend les pages pendant le temps de construction (build-time), ce qui donne lieu à des fichiers HTML statiques. Cette approche est excellente pour le SEO tout en maintenant les avantages des SPA pour l'UX. Elle exploite habilement les capacités de rendu côté serveur (SSR) de Vue, que vous pouvez observer dans le code source.

Ces éléments constituent la fondation de VitePress, le rendant idéal pour créer des blogs, de la documentation, et d'autres sites web centrés sur le contenu. Bien qu'il supporte les données dynamiques, cet aspect sera exploré dans une autre série.

Équipé d'un thème par défaut, VitePress facilite la création de sites de documentation attrayants. Le thème par défaut, disponible pour exploration dans la documentation de VitePress et son code source, est simplement une bibliothèque Vue intégrée composée de composants, de composables, et de CSS, facilement remplaçables pour créer des thèmes personnalisés.

Comprendre la véritable implication du slogan clarifie pourquoi VitePress est choisi pour développer un blog ; c'est un outil polyvalent pour les sites centrés sur le contenu au-delà de la simple documentation.

Histoire ​

Développé par Evan You aux côtés de Vite, VitePress a testé Vite dans un cadre réel, assurant sa praticité et sa convivialité. VitePress a évolué à partir de son prédécesseur VuePress, passant de Webpack et Vue 2 à Vite et Vue 3, offrant des améliorations significatives en matière de performance et d'expérience développeur.

VitePress est populaire pour la création de sites de documentation ou de blogs comme The Vue Point, le blog officiel de Vue.js. Sa fine couche au-dessus de Vite garantit qu'il reste hautement extensible et personnalisable, avec l'assurance d'un soutien continu.

Initialiser le Projet ​

Armés d'une meilleure compréhension de VitePress, nous pouvons initier un nouveau projet appelé "Garabit." Vous pouvez accéder au code source sur garabit.

Bien qu'initialement conçu pour les sites de documentation au sein de projets existants, le processus d'installation pourrait être amélioré. J'ai mis en évidence cela dans deux demandes de tirage sur le dépôt VitePress : feat(cli): support custom npm scripts prefix et feat(cli): support custom srcDir.

Tout d'abord, créez un dossier pour notre projet :

mkdir garabit

Ensuite, initialisez npm à l'intérieur de ce dossier et installez VitePress :

pnpm init
pnpm add -D vitepress

Enfin, créez le projet VitePress :

pnpm vitepress init

Répondez aux questions (appuyez sur entrer pour les valeurs par défaut, que nous ajusterons plus tard) :

┌  Bienvenue dans VitePress !
│
◇  Où VitePress doit-il initialiser la configuration ?
│  ./
│
◇  Titre du site :
│  Mon Projet Génial
│
◇  Description du site :
│  Un Site VitePress
│
◇  Thème :
│  Thème par Défaut
│
◇  Utiliser TypeScript pour les fichiers de configuration et de thème ?
│  Oui
│
◇  Ajouter des scripts npm VitePress au package.json ?
│  Oui
│
└  Terminé ! Maintenant, exécutez pnpm run docs:dev et commencez à écrire.

Explorer le Projet ​

Nous avons maintenant un projet VitePress flambant neuf. Examinons la structure du projet :

.
├── .vitepress
│   └── config.mts
├── api-examples.md
├── index.md
├── markdown-examples.md
├── package.json
└── pnpm-lock.yaml

Le niveau racine contient nos fichiers Markdown, représentant les pages de notre blog, avec des noms de fichiers (et répertoires) correspondant aux URL des pages. index.md sert de page d'accueil. Bien que cette structure soit basique, nous l'affinerons dans de futurs articles.

Étant centré sur le contenu, la configuration et les éléments liés au thème de VitePress résident dans le répertoire .vitepress, où le fichier config.mts configure le thème, les plugins, le chargement de données, et plus, écrit en TypeScript. Nous approfondirons cela dans les articles à venir.

Améliorer l'Expérience Développeur (DX) ​

Bien que convenable pour les sites de documentation, notre blog personnalisé nécessite des dépendances supplémentaires pour améliorer l'expérience développeur (DX). Nous allons intégrer deux dépendances :

• Tailwind CSS : Un framework CSS utilitaire pour concevoir efficacement des designs personnalisés.
• unplugin-vue-components : Un plugin Vite pour l'importation automatique de composants Vue.

Tailwind CSS ​

Nous allons tirer parti de Tailwind CSS pour styliser notre thème personnalisé. Ce framework CSS utilitaire propose des capacités de conception puissantes et conviviales.

Commencez par installer Tailwind CSS :

pnpm add -D tailwindcss postcss autoprefixer

Créez le fichier de configuration pour Tailwind CSS :

npx tailwindcss init -p

Nous allons configurer Tailwind CSS au fur et à mesure de notre avancée.

Importation Automatique des Composants Vue ​

Nous utiliserons unplugin-vue-components pour l'importation automatique des composants Vue, un plugin Vite permettant l'importation de composants à la demande. Ce processus automatisé fait gagner un temps considérable en éliminant l'importation manuelle par fichier. Les composants ne sont pas disponibles globalement, ce qui atténue l'impact sur la performance, car nos fichiers sont transformés via un plugin rollup, ajoutant un import en haut du fichier uniquement si le composant est utilisé, un témoignage de la philosophie à la demande.

Tout d'abord, installez unplugin-vue-components :

pnpm add -D unplugin-vue-components

Ensuite, intégrez-le dans le fichier config.mts :

import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
  vite: {
    plugins: [Components()],
  },
})

Nous configurerons unplugin-vue-components plus en détail plus tard.

Prêts pour la Prochaine Étape ​

Avec notre projet VitePress maintenant doté de Tailwind CSS et unplugin-vue-components, nous sommes prêts à commencer à développer notre blog.

Dans l'article suivant, nous examinerons les fondamentaux de VitePress et créerons un thème personnalisé pour notre blog.