Dans le paysage numérique actuel, qui évolue rapidement, il est essentiel de disposer d’une documentation ou d’un site de blog bien organisé et visuellement attrayant pour attirer l’attention de votre public et maintenir son intérêt. Mais comment y parvenir sans consacrer des heures interminables au développement web ?
Cet article explique comment créer et personnaliser un site de documentation et de blog rapide en utilisant VuePress, un générateur de site statique (SSG) minimaliste mais puissant.
Qu’est-ce que VuePress ?
VuePress est un framework open source spécialisé dans la création de sites web statiques, principalement orientés vers la documentation et les blogs. Il a été créé par Evan You, le génie de Vue.js, et il incarne la philosophie de simplicité et de facilité d’utilisation pour laquelle Vue.js est connu.
Pourquoi utiliser VuePress ?
Voici quelques raisons convaincantes pour lesquelles VuePress pourrait être le choix idéal pour vous.
- Simplicité Markdown : VuePress simplifie la création de contenu avec Markdown, ce qui facilite la rédaction et la structuration du contenu sans formatage complexe.
- Intégration Vue.js : VuePress intègre Vue.js de manière transparente, ce qui permet d’utiliser des éléments web interactifs et dynamiques pour une expérience utilisateur attrayante.
- Performance et personnalisation : VuePress offre d’excellentes performances avec des sites web statiques à chargement rapide et des options de personnalisation étendues pour s’adapter à votre style et à vos besoins.
Démarrer avec VuePress
Avant de plonger dans VuePress, assurez-vous que Node.js ou Yarn Classic est installé sur votre ordinateur. Il y a deux façons de démarrer avec VuePress : soit vous utilisez le générateur create-vuepress-site, qui vous aidera à construire la structure de base de votre site VuePress, soit vous utilisez l’installation manuelle.
Pour cet article, nous allons utiliser la méthode d’installation manuelle.
- Créez un nouveau répertoire et modifiez-le :
mkdir vuepress-starter && cd vuepress-starter- Initialisez avec votre gestionnaire de paquets préféré. Pour cet article, nous utiliserons Yarn :
yarn init- Installez VuePress dans votre projet en tant que dépendance de développeur :
yarn add -D vuepress- Créez un dossier docs pour contenir tout votre code et créez ensuite un fichier README.md, qui sert de fichier d’index de votre projet, similaire à index.html :
mkdir docs && echo '# Hello VuePress' > docs/README.md- Ouvrez votre projet dans un éditeur de code et ajoutez les scripts suivants à votre fichier package.json afin de pouvoir servir et construire votre site :
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},Vous pouvez maintenant servir votre site en exécutant la commande yarn dev. VuePress démarrera votre serveur de développement à l’adresse http://localhost:8080.
Vous avez maintenant créé un site de documentation. Vous remarquerez que VuePress propose d’emblée un thème par défaut propre et minimaliste. Cependant, il est hautement personnalisable, ce qui vous donne la liberté de créer un aspect et une convivialité uniques pour votre site web.
Créer des pages de documentation
VuePress suit une structure de répertoire simple pour organiser la documentation. Dans le dossier de votre projet, vous trouverez le répertoire docs que nous avons créé, où vous pouvez créer des fichiers Markdown (.md) pour vos pages de documentation.
Par exemple, vous pouvez créer des fichiers tels que get-started.md, usage.md et troubleshooting.md. Ces fichiers deviennent automatiquement des itinéraires accessibles lorsque vous naviguez vers http://localhost:8080/getting-started, http://localhost:8080/usage et http://localhost:8080/troubleshooting.
Pour améliorer l’organisation de votre documentation, vous pouvez créer des dossiers dédiés aux pages de documentation connexes. Par exemple, vous pouvez créer un dossier appelé guide et l’organiser avec des guides spécifiques comme using-kinsta-stsh.md. Lorsque vous utilisez cette structure, le contenu de using-kinsta-stsh.md devient accessible via une URL telle que http://localhost:8080/guide/using-kinsta-stsh.
Vous pouvez également créer un fichier README.md ou index.md à la racine du dossier guide. Ce fichier servira de page d’index, permettant aux utilisateurs de naviguer vers http://localhost:8080/guide/ et d’accéder facilement au contenu à l’aide d’une barre latérale que vous apprendrez à configurer dans la section suivante.
Dans cet exemple de dépôt VuePress, vous remarquerez que tous ces fichiers ont été créés et que du contenu markdown a été ajouté à chacun d’entre eux. N’hésitez pas à créer vos fichiers selon vos préférences, soit en partant de zéro pour répondre à vos besoins spécifiques, soit en vous inspirant du contenu disponible dans le dépôt.
Personnaliser l’apparence de VuePress
Une fois que vous avez créé votre site de documentation avec du contenu, vous pouvez trouver qu’il est difficile de naviguer, surtout si vous avez beaucoup de fichiers à gérer. VuePress vous permet toutefois de personnaliser la structure de navigation de votre site pour le rendre plus convivial et mieux organisé.
Pour personnaliser l’apparence et la navigation de votre site, créez un dossier .vuepress dans le répertoire racine de votre projet. Ce dossier contiendra les fichiers de configuration et les ressources liées à votre site VuePress.
Configuration de la navigation
Dans le dossier .vuepress, créez un fichier config.js. Vous pouvez également utiliser d’autres formats de fichiers tels que YAML (.yml), TOML (.toml) ou TypeScript (.ts) pour votre configuration.
Dans votre fichier config.js, vous pouvez définir la structure de navigation de votre site à l’aide de l’objet themeConfig. Voici un exemple de configuration :
module.exports = {
title: 'Kinsta Vuepress',
description: 'A VuePress QuickStart for Kinsta',
themeConfig: {
nav: [
{
text: 'Guide',
link: '/guide/',
},
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
sidebar: {
'/guide/': [
{
title: 'Guide',
collapsable: false,
children: ['', 'using-kinsta-stsh'],
},
],
},
},
};Dans cet exemple, nous configurons les sites title et description, nous définissons les liens de navigation et nous mettons en place une colonne latérale pour la section /guide/.
Le tableau nav spécifie les liens de navigation en haut de votre site. L’objet sidebar définit la structure de la colonne latérale pour des sections spécifiques. Dans ce cas, il est configuré pour la section /guide/.
Vous pouvez en savoir plus sur la configuration des barres de navigation dans la documentation VuePress.
Style
VuePress vous permet de personnaliser l’apparence de votre site à l’aide de styles. Vous pouvez soit remplacer les styles par défaut à l’aide de certaines variables définies, soit définir votre propre style. Pour cela, créez un dossier styles dans le dossier .vuepress
Pour appliquer des modifications simples au style du pré-réglage par défaut ou définir des variables à utiliser ultérieurement, vous pouvez créer un fichier palette.styl dans le dossier .vuepress/styles. Voici quelques variables prédéfinies que vous pouvez modifier :
// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419pxCes variables peuvent être utilisées pour maintenir un style cohérent sur l’ensemble de votre site. VuePress offre également un moyen pratique d’ajouter des styles supplémentaires. Vous pouvez créer un fichier index.styl dans le dossier .vuepress/styles où vous pouvez utiliser la syntaxe CSS normale :
.content {
font-size 30px
}Pour en savoir plus sur le style de VuePress, consultez la documentation officielle.
Utilisation de composants
VuePress prend en charge l’utilisation de composants pour améliorer la fonctionnalité et l’apparence de vos pages. Vous pouvez créer des composants Vue et les inclure dans vos fichiers Markdown. Créez un composant
components dans .vuepres, puis tous les fichiers *.vue trouvés dans .vuepress/components sont automatiquement enregistrés en tant que composants globaux.
Par exemple, vous pouvez créer deux composants, HomeOptions.vue et HostingBanner.vue :
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vueDans ces fichiers de composants vue.js, vous pouvez ajouter des codes CSS. Ajoutons du code aux composants HomeOptions. vue et HostingBanner.vue.
Ajoutez le code ci-dessous à HomeOptions.vue :
<template>
<div class="options">
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/static-site-quick-start-examples/"
target="_blank"
>
<h3>Quick Start Examples</h3>
</a>
<p>Explore quick start examples for setting up static sites.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/getting-started-static-site-hosting/"
target="_blank"
>
<h3>Getting Started</h3>
</a>
<p>Learn how to get started with static site hosting.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/manage-static-sites/"
target="_blank"
>
<h3>Manage Static Sites</h3>
</a>
<p>Discover how to efficiently manage your static sites.</p>
</div>
</div>
</template>
<style scoped>
a {
color: #2c3e50;
}
a:hover {
color: #5333ed;
}
.options {
display: flex;
gap: 10px;
margin: 40px 0;
}
.option {
border: 2px solid #eaecef;
border-radius: 5px;
padding: 10px;
}
</style>Ajoutez également le code ci-dessous à HostingBanner.vue :
<template>
<div class="banner">
<p>Host Your Static Site With Kinsta for Free!</p>
<a
href="https://kinsta.com/docs/static-site-hosting/"
target="_blank"
class="btn"
>Read More</a
>
</div>
</template>
<style> scoped>
.banner {
background: rgb(156, 85, 34);
background: linear-gradient(
90deg,
rgba(156, 85, 34, 1) 0%,
rgba(32, 50, 103, 1) 42%,
rgba(13, 18, 25, 1) 69%,
rgba(22, 47, 60, 1) 100%
);
color: #fff;
padding: 20px;
border-radius: 5px;
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
}
.banner p {
width: 600px;
font-size: 40px;
font-weight: bold;
text-align: center;
line-height: 50px;
}
.banner .btn {
border-radius: 5px;
padding: 15px;
color: #1f1f1f;
font-weight: bold;
background: #fff;
display: inline-block;
margin-bottom: 10px;
}
.banner .btn:hover {
background: #111319;
color: #fff;
}
</style>À l’intérieur de n’importe quel fichier Markdown, vous pouvez alors utiliser directement les composants (les noms sont déduits des noms de fichiers) :
<HomeOptions/>
<HostingBanner/>Pour en savoir plus sur les composants dans VuePress, consultez la documentation.
Personnaliser la page d’accueil
Dans VuePress, le thème par défaut propose une page d’accueil prédéfinie que vous pouvez utiliser pour créer un point de départ attrayant et informatif pour votre site. Pour utiliser cette présentation de page d’accueil, vous devez spécifier home: true et inclure quelques méta-données supplémentaires dans le frontmatter YAML de votre fichier README.md racine.
Voici un exemple d’article de tête YAML :
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---Toutes ces configurations font que la page d’accueil de votre documentation ressemble à ceci :
Il convient de noter que vous pouvez désactiver les valeurs heroText et tagline ou toute autre valeur en définissant leurs champs correspondants à null si vous préférez une mise en page plus simple ou ne pas l’inclure. Tout contenu que vous incluez après le frontmatter YAML (c’est-à-dire la section des métadonnées) sera traité comme du Markdown normal et sera rendu après la section des caractéristiques.
Si vous souhaitez une page d’accueil entièrement personnalisée, VuePress prend également en charge les mises en page personnalisées. En outre, vous pouvez créer un pied de page en texte riche en utilisant la syntaxe Markdown Slot, ce qui offre une plus grande flexibilité dans l’affichage du contenu du pied de page. Voici un exemple de définition d’un pied de page en texte enrichi :
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::Dans ce cas, le contenu de la section ::: slot footer vous permet d’inclure des liens et des informations supplémentaires dans la zone de pied de page de votre page d’accueil.
Maintenant que vous savez comment effectuer les personnalisations ci-dessus, ajoutez les composants créés précédemment à la page d’accueil et supprimez certaines options afin d’améliorer l’aspect de la page d’accueil :
---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
<HomeOptions/>
<HostingBanner/>
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
En suivant ces techniques de personnalisation de VuePress, vous pouvez créer un site de documentation qui non seulement fournit un contenu précieux, mais offre également une excellente expérience utilisateur avec une navigation organisée et un style attrayant.
Vous pouvez en savoir plus sur la personnalisation du thème par défaut dans la documentation.
Créer une section blog avec VuePress
Ajouter une section blog à votre site VuePress est un jeu d’enfant puisque VuePress vous permet d’écrire des composants Vue personnalisés qui peuvent être insérés dans n’importe quel fichier Markdown. Créons un composant qui rendra la liste des articles du blog.
Créez un fichier BlogIndex.vue dans le dossier components et ajoutez le code suivant :
<template>
<div>
<div v-for="post in posts" v-bind:key="post.path">
<h2>
<router-link> :to="post.path">{{ post.frontmatter.title }}</router-link>
</h2>
<p>{{ post.frontmatter.description }}</p>
<p><router-link> :to="post.path">Read more</router-link></p>
</div>
</div>
</template>
<script>>
export default {
computed: {
posts() {
return this.$site.pages
.filter(
(x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
)
.sort(
(a, b) =>
new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
);
},
},
};
</script>Dans l’extrait de code fourni, vous définissez un modèle Vue qui parcourt en boucle les articles de votre blog à l’aide de v-for, en affichant le titre de l’article, sa description et un lien « read more » pour chaque article.
La section script exporte un composant Vue qui calcule et récupère les articles du blog. Ces articles sont filtrés en fonction de leur chemin d’accès (commençant par /blog/) et de l’absence d’un attribut frontmatter blog_index. Ils sont ensuite triés par date dans l’ordre décroissant afin de présenter les derniers articles en premier.
Lorsque vous créez de nouveaux articles de blog, vous devez spécifier la date de publication dans les informations de l’attribut frontmatter. Cela permettra de trier les articles de manière à ce que les plus récents apparaissent en premier.
Pour stocker les articles de blog, créez un dossier nommé blog à la racine du projet. Dans ce dossier, ajoutez un fichier README.md. Il s’agira de l’index du blog, et c’est là que vous inclurez le composant BlogIndex pour répertorier tous les articles du blog.
---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />Veillez à ajouter l’attribut blog_index frontmatter, car il permet de s’assurer que l’index du blog lui-même n’est pas listé parmi les différents articles du blog. Cet attribut est utilisé lors du filtrage des articles dans la propriété posts computed du composant BlogIndex.vue.
Ensuite, créez un dossier blog à la racine de votre projet qui stockera tous les articles du blog et créera chaque article. Par exemple, créez un fichier first-post.md et ajoutez le contenu markdown suivant :
---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.Pour chaque article de blog, veillez à définir les réglages essentiels de la page d’accueil, tels que le titre de l’article, la date et d’autres méta-données pertinentes. Cette organisation méticuleuse garantit une présentation cohérente de vos articles de blog et offre à votre public une expérience de lecture attrayante.
Enfin, vous pouvez ajouter la navigation du blog à votre barre de navigation dans le fichier .vuepress/config.js :
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],Vous pouvez faire bien d’autres choses avec VuePress, comme ajouter des extensions, utiliser un thème séparé ou même créer votre propre thème.
Déployer un site statique VuePress sur Kinsta
Kinsta vous permet d’héberger gratuitement jusqu’à 100 sites web statiques. Vous pouvez le faire en poussant votre code vers votre fournisseur Git préféré (Bitbucket, GitHub ou GitLab), puis en le déployant sur Kinsta.
Avant de pousser vos fichiers vers un fournisseur Git, créez un fichier .gitignore à la racine de votre projet pour spécifier les fichiers et dossiers que Git doit ignorer lors de la poussée de votre code :
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/publicPour ce guide, nous utilisons GitHub. Créez un dépôt sur GitHub pour y déposer votre code source. Une fois que votre dépôt est prêt, suivez les étapes suivantes pour déployer votre site statique sur Kinsta :
- Connectez-vous ou créez un compte pour afficher votre tableau de bord MyKinsta.
- Autorisez Kinsta avec votre fournisseur Git.
- Cliquez sur Sites statiques dans la colonne latérale gauche, puis cliquez sur Ajouter un site.
- Sélectionnez le dépôt et la branche à partir desquels vous souhaitez déployer.
- Attribuez un nom unique à votre site.
- Ajoutez les paramètres de construction dans le format suivant :
- Commande de construction :
npm run build - Version du nœud :
16.20.0 - Répertoire de publication :
./docs/.vuepress/distoupublic
- Commande de construction :
- Enfin, cliquez sur Créer un site.
Et le tour est joué ! En quelques secondes, vous disposez d’un site déployé. Un lien est fourni pour accéder à la version déployée de votre site. Vous pourrez par la suite ajouter votre domaine personnalisé et votre certificat SSL si vous le souhaitez.
Comme alternative à l’hébergement de site statique, vous pouvez opter pour le déploiement de votre site statique avec l’hébergement d’application de Kinsta, qui offre une plus grande flexibilité d’hébergement, une plus large gamme d’avantages et l’accès à des fonctionnalités plus robustes. Par exemple, l’évolutivité, le déploiement personnalisé à l’aide d’un fichier Docker et des analyses complètes englobant des données en temps réel et historiques.
Résumé
VuePress est un outil polyvalent et puissant pour créer rapidement des sites de documentation et de blog. Grâce à sa configuration simple, ses thèmes personnalisables et ses plugins, vous pouvez créer une plateforme informative et visuellement attrayante pour votre public.
Commencez à créer votre site VuePress dès aujourd’hui et partagez vos connaissances avec le monde entier en l’hébergeant gratuitement sur notre hébergement de sites statiques !
Vous avez utilisé VuePress pour construire quelque chose ? N’hésitez pas à partager vos projets et vos expériences avec nous dans la section des commentaires ci-dessous.
Joel est un développeur d'interfaces publiques qui travaille chez Kinsta en tant que rédacteur technique. Il est un enseignant passionné par l'open source et a écrit plus de 200 articles techniques, principalement autour de JavaScript et de ses frameworks.
Laisser un commentaire