Du thème par défaut au thème personnalisé avec VitePress

Dans l'article précédent, nous avons initialisé notre projet en utilisant le modèle VitePress. Par défaut, VitePress est livré avec un thème intégré conçu pour créer des sites de documentation. Cependant, nous souhaitons développer un site de blog, nécessitant ainsi la création d'un thème personnalisé.

Thème Personnalisé ​

Pour construire un thème personnalisé, deux fichiers doivent être créés :

• src/.vitepress/theme/index.ts : Cela sert de point d'entrée pour notre thème personnalisé, comparable au fichier main.ts dans un projet Vite + Vue.
• src/.vitepress/theme/Layout.vue : Ce fichier constitue le principal composant Vue de notre thème personnalisé, analogue au fichier App.vue dans un projet Vite + Vue.

Nous avons établi un dossier theme au sein du répertoire .vitepress. C'est l'emplacement désigné pour tous les fichiers associés à notre thème personnalisé. Il peut être vu de manière similaire au dossier src dans un projet Vite + Vue et adoptera une structure parallèle. Une explication plus approfondie sera fournie dans l'article à venir.

Fichier index.ts ​

Le fichier index.ts est automatiquement reconnu par VitePress et, comme le fichier main.ts dans un projet Vite + Vue, il est nécessaire pour charger le fichier Layout.vue.

import { Theme } from 'vitepress'
import Layout from './Layout.vue'

export default {
  Layout,
} satisfies Theme

Fichier Layout.vue ​

Pour commencer, nous pouvons simplement insérer un élément h1 avec le texte "Garabit Blog" dans le fichier Layout.vue.

<template>
  <div>
    <h1>Garabit Blog</h1>
  </div>
</template>

Pour lancer le serveur de développement, exécutons la commande suivante :

pnpm run docs:dev

Naviguons vers http://localhost:5173 pour constater le bon fonctionnement de notre thème personnalisé.

Splendide !

Affichage du Contenu Markdown ​

Ceci marque un début prometteur, mais nous devons rendre le contenu markdown pour améliorer la fonctionnalité de notre blog. À cette fin, le composant Content fourni par VitePress est essentiel.

<template>
  <div>
    <h1>Garabit Blog</h1>

    <Content />
  </div>
</template>

Ce composant rendra automatiquement le contenu markdown de la page actuelle. Pour l'heure, il n'affiche rien car le contenu du fichier index.md est vide. Supprimons toute la frontmatter et ajoutons un peu de texte :

Hey 👋,

This is the index page.

Une fonctionnalité clé de VitePress est son approche de la gestion du routage. Par défaut, le fichier index.md représente la page d'accueil. Ainsi, naviguer vers http://localhost:5173 affichera le contenu du fichier index.md. D'autres fichiers markdown sont accessibles par leurs noms de fichiers. Par exemple, about.md est accessible via http://localhost:5173/about.html. Pour lier à une autre page, utilisons la balise a avec l'attribut href pointant vers le nom du fichier.

Hey 👋,

This is the index page.

[Go to the api-examples page](/api-examples)

En cliquant sur le lien, la page ne se rechargera pas ; au lieu de cela, le contenu se renouvellera. Cette fonctionnalité de VitePress facilite la navigation fluide.

La vidéo ci-dessus démontre que la page reste sans rechargement lors de la navigation entre les pages. La 'flèche', située à gauche de l'icône de maison, indique les mises à jour de page sans rechargement. Sinon, la flèche apparaîtrait comme une croix.

Suppression du Thème par Défaut ​

Avec les éléments fondamentaux pour un thème personnalisé désormais établis, nous pouvons éliminer des aspects du thème par défaut.

Commençons par supprimer le lien dans le fichier index.md :

Hey 👋,

This is the index page.

[Go to the api-examples page](/api-examples)

Ensuite, supprimons les fichiers api-examples.md et markdown-examples.md du répertoire racine.

Enfin, éliminons les lignes de thème associées dans le fichier config.mts :

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

export default defineConfig({
  title: 'My Awesome Project', 
  description: 'A VitePress Site', 
  themeConfig: { 
    // https://vitepress.dev/reference/default-theme-config
    nav: [ 
      { text: 'Home', link: '/' }, 
      { text: 'Examples', link: '/markdown-examples' }, 
    ], 

    sidebar: [ 
      { 
        text: 'Examples', 
        items: [ 
          { text: 'Markdown Examples', link: '/markdown-examples' }, 
          { text: 'Runtime API Examples', link: '/api-examples' }, 
        ], 
      }, 
    ], 

    socialLinks: [ 
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }, 
    ], 
  }, 

  vite: {
    plugins: [Components()],
  },
})

Nous sommes désormais pleinement équipés et prêts à créer notre thème personnalisé.