Les bases d'un thème personnalisé

Dans l'article précédent, nous avons initialisé votre 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 web de documentation. Cependant, nous allons développer un site de blog, ce qui nécessite 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 : Il 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 : Il constitue le composant principal 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 considéré de manière similaire au dossier src dans un projet Vite + Vue et adoptera une structure parallèle. Une explication supplémentaire 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 démarrer le serveur de développement, exécutons la commande suivante :

pnpm run docs:dev

Naviguons vers http://localhost:5173 pour constater que notre thème personnalisé est opérationnel.

Magnifique !

Affichage du Contenu Markdown ​

C'est un bon un début, mais nous devons rendre le contenu markdown pour rendre utilisable notre blog. À cette fin, le composant Content fourni par VitePress est essentiel.

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

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

Ce composant rend automatiquement le contenu markdown de la page actuelle. Pour l'heure, il n'affiche rien car le contenu de index.md est vide. Supprimons tout le front matter 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. Tous 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 de fichier. Simple !

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 mettra à jour. Cette fonctionnalité de VitePress facilite la navigation fluide.

La vidéo ci-dessus démontre que la page n'est pas rechargée 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 s'afficherait comme une croix.

Suppression du Thème Par Défaut ​

Avec les éléments fondamentaux pour un thème personnalisé maintenant établis, nous pouvons retirer les derniers éléments 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, retirons les lignes de thème associées du 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()],
  },
})

Vous êtes maintenant pleinement équipé et prêt à créer votre thème personnalisé.