En marche avec VuePress

Apprenez à utiliser VuePress, un générateur de site statique, pour créer un site de documentation

Un générateur de site statique récupère les fichiers source et génère un site Web statique complet. Les générateurs de sites statiques nécessitent moins de ressources serveur, sont évolutifs et peuvent gérer des volumes de trafic élevés. Aujourd'hui, de nombreux générateurs de sites statiques sont disponibles et utilisés à toutes sortes de fins. Certains sont utilisés uniquement pour les sites de documentation, pour un site Web avec un blog ou pour les sites de documentation et les blogs. Auparavant, j’utilisais Gitbook pour des sites de documentation et j’ai décidé d’utiliser VuePress.

VuePress est un générateur de site statique construit sur Vue.js. Il a été construit pour prendre en charge les besoins en documentation pour les projets liés à Vue.js. VuePress facilite l'ajout de documentation à des projets existants et le contenu peut être écrit dans Markdown. Le thème par défaut utilisé est optimisé pour les sites de documentation technique. Je vais vous montrer comment démarrer avec VuePress en construisant un site de documentation technique minimale.

Configuration du projet

VuePress nécessite Node.js version 8 ou supérieure. En outre, vous aurez besoin de l’installation de Vue CLI (j’utilise Vue 2 en même temps). Ouvrez la ligne de commande et suivez les instructions ci-dessous pour configurer le projet:

1. Run vue create vuepress-doc . Cela devrait vous demander de sélectionner un préréglage. Sélectionnez par défaut et appuyez sur Entrée
2. Exécutez cd vuepress-doc pour changer de répertoire dans le répertoire du projet Vue.
3. Ajoutez une dépendance VuePress au projet en exécutant la commande npm install -D vuepress .
4. Exécutez mkdir docs pour créer un nouveau répertoire nommé docs . Cela contiendra des fichiers pour les documents VuePress.
5. Basculez vers le répertoire de documents ( cd docs ) et créez un nouveau répertoire en exécutant mkdir .vuepress . .

Les instructions ci-dessus devraient vous laisser avec un projet Vue qui alimentera le site Web de documentation que nous allons créer avec VuePress. Le dossier docs contient les fichiers du site Web et le dossier .vuepress contient des fichiers permettant de définir la configuration, les composants, les styles, etc. de VuePress. Ouvrez package.json et ajouter les scripts suivants:

 "docs: dev" :   "vuepress dev docs" 
 "docs: build" :   "vuepress build docs "

La commande vuepress dev docs va démarrer le serveur de développement local pour VuePress, avec docs comme nom du répertoire de sélection du contenu. La commande vuepress build génère des ressources statiques pouvant être déployées sur tout environnement d'hébergement.

Ajout de la page d'accueil

Maintenant que le projet est configuré, nous devons ajouter une page d'accueil. , qui sera affiché par la route / . Ajouter un nouveau fichier .vuepress / config.js avec le contenu ci-dessous.

 module .  exportations  =   {
  titre :   "VuePress" 
  description :   "Mes documents propulsés par VuePress" 
} ; 

Ce fichier est essentiel pour la configuration de VuePress. La propriété title sera définie comme titre pour le site. Ce sera le préfixe de tous les titres de page et sera affiché dans la barre de navigation du thème par défaut. La description est la description du site. Cela sera rendu sous forme de balise dans la page HTML.

Dans le dossier docs, ajoutez un nouveau fichier README.md . Ouvrez-le et ajoutez-y le contenu ci-dessous.

 ---
accueil: vrai
heroImage: https://vuepress.vuejs.org/hero.png
actionText: Commencer →
actionLink: / guide /
fonctionnalités:
  - titre: Simplicity First

    détails: Une configuration minimale avec une structure de projet centrée sur le démarquage vous aide à vous concentrer sur l'écriture.
  - titre: Vue-Powered

    Détails: Profitez de l'expérience de développement de Vue + webpack, utilisez les composants Vue dans Markdown et développez des thèmes personnalisés avec Vue.
  - titre: performant

    détails: VuePress génère du code HTML statique pré-rendu pour chaque page et s’exécute en tant que SPA une fois la page chargée.
footer: Copyright © 2019 - Peter Mbanugo
---

Aussi simple que 1, 2, 3

`` `bash
# installer
filé global ajouter vuepress
# OU npm installer -g vuepress

# créer un fichier de démarques
echo '# Hello VuePress'> LISEZMOI.md

# commence à écrire
vuepress dev

# construire en fichiers statiques
vuepress build
`` `

Nous utilisons le thème par défaut fourni avec VuePress. Il fournit une mise en page par défaut de la page d'accueil, que nous pouvons personnaliser en spécifiant certaines variables prédéfinies dans l'avant-plan YAML du fichier. Définir la variable home sur true lui indique de styliser la page en utilisant le style de page d'accueil par défaut. Ce style par défaut rend une image de héros avec du texte et une section de fonctionnalités. Le texte provient du titre et de la description que vous avez définis dans .vuepress / config.js . Tout ce qui se trouve après l’avant-plan YAML sera analysé comme un Markdown normal et restitué après la section caractéristiques. Voyons à quoi ressemble ce que nous avons dans le navigateur. Ouvrez la ligne de commande et exécutez npm run docs: dev . Cela devrait démarrer le serveur de développement local et vous pouvez accéder au site Web par défaut à localhost: 8080.

Ce que cela nous donne est une belle- recherche de la page d’accueil avec une barre de navigation.La barre de navigation a par défaut le titre du site Web et un champ de recherche.

Ajout d’une barre de navigation

Ajoutons une barre de navigation qui permet de naviguer vers d’autres sections du site Web. themeConfig propriété dans .vuepress / config.js . Ouvrez ce fichier et ajoutez les propriétés suivantes à l'objet exporté.

 themeConfig :   {
  nav :   [
     { texte :   "Guide"  lien :   "/ guide /"   } 
     { texte :   "Auteur"  lien :   "https://pmbanugo.me"   } 
  ] ; 
} 

Cela nous donne deux liens sur la barre de navigation. Si vous cliquez sur le lien Guide il sera redirigé vers une page 404. C’est parce qu’il n’ya pas de fichier pour résoudre cette route. Le paramètre de route par défaut sera corrigé de / à de README.md dans le répertoire racine, / guide / sera résolu en /guide/README.md et /guide/setup.html deviendra le /guide/setup.md .

Continuez et créez un nouveau dossier guide . un fichier README.md avec le contenu suivant:

 # Introduction

VuePress est composé de deux parties: un générateur de site statique minimaliste avec un système de thème alimenté par Vue et un thème par défaut optimisé pour la rédaction de documentation technique. Il a été créé pour répondre aux besoins de documentation des sous-projets de Vue.

Chaque page générée par VuePress dispose de son propre code HTML statique prédéfini, offrant d'excellentes performances de chargement et respectant les règles de référencement. Une fois la page chargée, toutefois, Vue reprend le contenu statique et le transforme en une application à page unique (SPA) complète. Des pages supplémentaires sont récupérées à la demande lorsque l'utilisateur navigue sur le site.

## Comment ça marche

Un site VuePress est en fait un SPA alimenté par [Vue] (http://vuejs.org/), [Vue Router] (https://github.com/vuejs/vue-router) et [webpack] (http: / /webpack.js.org/). Si vous avez déjà utilisé Vue auparavant, vous remarquerez l’expérience de développement que vous connaissez lorsque vous écrivez ou développez des thèmes personnalisés (vous pouvez même utiliser Vue DevTools pour déboguer votre thème personnalisé!).

Pendant la construction, nous créons une version de l'application rendue par le serveur et rendons le code HTML correspondant en visitant virtuellement chaque itinéraire. Cette approche est inspirée de la commande `nuxt generate` de [nuxtgenerate`de[Nuxt] (https://nuxtjs.org/) et d'autres projets tels que [Gatsby] (https://www.gatsbyjs.org/).

Chaque fichier Markdown est compilé en HTML avec [markdown-it] (https://github.com/markdown-it/markdown-it), puis traité en tant que modèle d'un composant Vue. Cela vous permet d’utiliser directement Vue à l’intérieur de vos fichiers Markdown et est idéal lorsque vous devez incorporer du contenu dynamique.

## Caractéristiques

- [Built-in Markdown extensions] (./ markdown.md) optimisé pour la documentation technique
- [Ability to leverage Vue inside Markdown files] (./ using-vue.md)
- [Vue-powered custom theme system] (./ custom-themes.md)
- [Automatic Service Worker generation] (../ config / README.md # serviceworker)
- [Google Analytics Integration] (../ config / README.md # ga)
- ["Last Updated" based on Git] (../ default-theme-config / README.md # dernière mise à jour)
- [Multi-language support] (./ i18n.md)
- Un thème par défaut avec:
  - mise en page sensible
  - [Optional Homepage] (page d'accueil ../ default-theme-config / README.md #)
  - [Simple out-of-the-box header-based search] (../ default-theme-config / README.md # recherche intégrée)
  - [Algolia Search] (../ default-theme-config / README.md # algolia-search)
  - Personnalisable [navbar] (../ default-theme-config / README.md # navbar) et [sidebar] (../ default-theme-config / README.md # sidebar)
  - [Auto-generated GitHub link and page edit links] (../ default-theme-config / README.md # git-repo-and-edit-links)

## Faire

VuePress est toujours un travail en cours. Il y a quelques choses qu'il ne supporte pas actuellement mais qui sont prévues:

- Support de plugin
- Support de blogs

Les contributions sont les bienvenues!

## Pourquoi pas ...?

### Nuxt

Nuxt est capable de faire ce que VuePress fait, mais il est conçu pour construire des applications. VuePress se concentre sur les sites statiques centrés sur le contenu et fournit des fonctionnalités adaptées à la documentation technique prête à l'emploi.

### Docsify / Docute

Les deux sont de grands projets et également à base de Vue. Sauf qu'ils sont tous deux entièrement axés sur l'exécution et ne sont donc pas adaptés au référencement. Si vous ne vous souciez pas de la SEO et que vous ne voulez pas vous soucier de l'installation de dépendances, ce sont toujours d'excellents choix.

### Hexo

Hexo a bien servi les utilisateurs de Vue docs. En fait, il nous reste probablement encore un long chemin à parcourir avant de migrer vers notre site principal. Le plus gros problème est que son système de thèmes est très statique et basé sur des chaînes - nous souhaitons vraiment utiliser Vue pour la mise en page et l'interactivité. De plus, le rendu de Markdown d'Hexo n'est pas le plus flexible à configurer.

### GitBook

Nous utilisons GitBook pour la plupart de nos documents de sous-projets. Le principal problème de GitBook est que ses performances de rechargement du développement sont intolérables avec une grande quantité de fichiers. Le thème par défaut a également une structure de navigation assez contraignante et le système de thèmes n’est, là encore, pas basé sur Vue. L’équipe derrière GitBook s’attache également à en faire un produit commercial plutôt qu’un outil à source ouverte.

Lorsque vous cliquez sur le lien Guide il est redirigé vers la page appropriée. Vous pouvez faire plus de choses sur la barre de navigation, mais par souci de brièveté, nous n’aurons que ces deux liens dans la barre de navigation. Consultez la documentation pour en savoir plus sur la désactivation de la barre de navigation pour une page donnée ou sur l'ajout d'un menu déroulant.

VuePress fournit également un moyen simple de configurer la navigation dans la barre latérale. Dans sa forme la plus élémentaire, vous pouvez définir la propriété themeConfig.sidebar sur un tableau de liens à afficher dans la barre latérale. Nous allons utiliser le formulaire le plus simple pour cette application pas à pas, mais si vous souhaitez en savoir plus sur les autres façons de configurer la barre latérale, la docs est votre meilleure ressource.

Ajouter un nouveau fichier getting-started.md dans le répertoire guide . Ouvrez-le et ajoutez-y le contenu.

 # Getting Started

::: AVERTISSEMENT NOTE DE COMPATIBILITE
VuePress nécessite Node.js> = 8.
:::

## Installation globale

Si vous voulez juste jouer avec VuePress, vous pouvez l'installer globalement:

`` `bash
# installer globalement
fil global add vuepress # OU npm installer -g vuepress

# créer un fichier de démarques
echo '# Hello VuePress'> LISEZMOI.md

# commence à écrire
vuepress dev

# construire
vuepress build
`` `

## À l'intérieur d'un projet existant

Si vous avez un projet existant et souhaitez conserver la documentation à l'intérieur du projet, vous devez installer VuePress en tant que dépendance locale. Cette configuration vous permet également d’utiliser des CI ou des services tels que Netlify pour un déploiement automatique lors de la diffusion.

`` `bash
# installer en tant que dépendance locale
fil ajouter -D vuepress # OU npm installer -D vuepress

# créer un répertoire de documentation
mkdir docs
# créer un fichier de démarques
echo '# Hello VuePress'> docs / README.md
`` `

::: Attention
Il est actuellement recommandé d'utiliser [Yarn] (https://yarnpkg.com/en/) au lieu de npm lors de l'installation de VuePress dans un projet existant utilisant Webpack 3.x comme dépendance. Npm ne parvient pas à générer l'arbre de dépendance correct dans ce cas.
:::

Ajoutez ensuite quelques scripts à `package.json`:

`` `json
{
  "scripts": {
    "docs: dev": "vuepress dev docs",
    "docs: build": "vuepress build docs"
  }
}
`` `

Vous pouvez maintenant commencer à écrire avec:

`` `bash
yarn docs: dev # OU npm exécuter docs: dev
`` `

Pour générer des actifs statiques, exécutez:

`` `bash
yarn docs: build # ou npm exécuter docs: build
`` `

Par défaut, les fichiers construits seront dans `.vuepress / dist`, qui peut être configuré via le champ` dest` dans `.vuepress / config.js`. Les fichiers créés peuvent être déployés sur n’importe quel serveur de fichiers statique. Voir [Deployment Guide] (./ deploy.md) pour des guides sur le déploiement vers des services populaires.

Ajouter l'encadré: ["/guide/", "/guide/getting-started"] à la propriété themeConfig de config.js . Lorsque vous enregistrez ce fichier, l'application doit recharger dans le navigateur et afficher une barre latérale pour l'itinéraire / guide .

title de l'avant-plan YAML pour la page ou utiliser un tableau . sous la forme de [link, text].

Recherche dans les documents

VuePress possède une fonctionnalité de recherche intégrée qui construit son index à partir des h1 h2 et h3 en-têtes.

Vous pouvez désactiver le champ de recherche avec themeConfig.search: false ou personnaliser combien de suggestions sera présenté avec themeConfig.searchMaxSuggestions . Vous pouvez également utiliser la recherche en texte intégral avec Algolia. Reportez-vous à la docs pour plus d’informations sur la configuration de cet outil.

C’est une solution

VuePress facilite la création d’un site de documentation technique. Au cours de ce blog, nous avons créé un site de documentation simple doté d’une fonctionnalité de recherche, d’une barre de navigation et d’une barre latérale. Il y a beaucoup plus d'options qui peuvent être configurées (par exemple, Service Worker et une page de disposition personnalisée). Pour en savoir plus, visitez vuepress.vuejs.org .

Pour plus d'informations sur la création de superbes applications Web

Vous voulez en savoir plus sur la création d'excellentes interfaces utilisateur? Découvrez Kendo UI – notre bibliothèque de composants d'interface utilisateur complète qui vous permet de créer rapidement des applications réactives de haute qualité. Il inclut tous les composants dont vous aurez besoin, des grilles et graphiques aux planificateurs et aux cadrans, ainsi qu’une bibliothèque construite uniquement pour Vue .