Image for post
Image for post

Create a simple i18n doc with VuePress

and deploy quickly with Netlify

Assitan Koné
Nov 21, 2018 · 6 min read

VuePress is static site generator made by creator of VueJS. Vue-apollo, Vue-test-utils, etc. use this tool for their documentation. We are going to see how we can use it to create a nice documentation and how we can deploy with Netlify.

Read my article on Netlify :


Demo.

The code is here.

Let’s get started.


Setup

You need to add vuepress globally. Create a directory named tuto-vuepress. Go inside and create a README.md file.

# install globally
yarn global add vuepress # OR npm install -g vuepress
➜ tuto-vuepress echo ‘# VuePress tuto’ > README.md

Create a directory named docs and put inside a directory named .vuepress. Then create inside a file named config.js. In this file we will add the name of the app, the routes, etc.

Add these commands in a package.json file. They allow to start and build.

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

Run the docs in your terminal then go to http://localhost:8080/. Everytime you make a modification, the app reloads automatically so you can see it.

yarn docs:dev # OR npm run docs:dev

Documentation

Context

This documentation will explain to your friend how to take care of your 3 pets, your dog Otis, your cat Bolt and your rabbit Goody during your vacation. Bonus, it’s also in French 😉

Let’s see what we are going to do.

Routes

We want to get this :

/otis
/otis/food.html
/otis/hoobies.html
/bolt
/bolt/food.html
/bolt/hoobies.html
/goody
/goody/food.html
/goody/hoobies.html

Internationalization

This documentation will be in english and french. We just need to start the url with /fr/.

/fr/otis
/fr/otis/food.html
/fr/otis/hoobies.html
/fr/bolt
/fr/bolt/food.html
/fr/bolt/hoobies.html
/fr/goody
/fr/goody/food.html
/fr/goody/hoobies.html

Sidebar

In the sidebar we’ll find the three categories with the sub-links. It’s important to add a README.md file in the root of each category if we want these URLs work.

Navbar

In the navbar there are the categories, languages and an external link to the repository of this project.

Assets

We’ll add a cute photo of theses pets.


At the end we’ll have this structure :

Image for post
Image for post

Dev

We add a quick introduction on the main README.md file (at the root of the project). You can write whatever you want.

Now, let’s create the routes and set up the locales in the config.js.

Image for post
Image for post
# config.jsmodule.exports = {
title: 'Tuto VuePress / Netlify',
description: 'Tuto VuePress / Netlify',
locales: {
'/': {
lang: 'en-US',
title: 'Tuto VuePress / Netlify',
description: 'How to take care of my pets',
},
'/fr/': {
lang: 'fr-FR',
title: 'Tuto VuePress / Netlify',
description: 'Comment s\'occuper de mes animaux',
},
},
};

Then we need to set the routes, sidebar and navbar. Everything is in the themeConfig part (still in the module.exports).

themeConfig: {
docsDir: 'docs',
locales: {
'/': {
label: 'English',
selectText: 'Languages',
sidebar: {
'/otis/': [
{
title: 'My dog - Otis',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/bolt/': [
{
title: 'Bolt',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/goody/': [
{
title: 'My rabbit - Goody',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/': [''], // fallback
},
nav: [
{text: '', link: '/'},
{text: 'Otis', link: '/otis/'},
{text: 'Bolt', link: '/bolt/'},
{text: 'Goody', link: '/goody/'},
{text: 'Github', link: 'https://github.com/Assitan/tuto-vuepress'},
],
},
'/fr/': {
label: 'Français',
selectText: 'Langues',
sidebar: {
'/fr/otis/': [
{
title: 'Mon chien - Otis',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/fr/bolt/': [
{
title: 'Mon chat - Bolt',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/fr/goody/': [
{
title: 'Mon lapin - Goody',
collapsable: false,
children: ['food', 'hobbies'],
},
],
'/': [''], // fallback
},
nav: [
{text: 'Otis', link: '/fr/otis/'},
{text: 'Bolt', link: '/fr/bolt/'},
{text: 'Goody', link: '/fr/goody/'},
{text: 'Github', link: 'https://github.com/Assitan/tuto-vuepress'},
],
},
},
},

I set collapsable to false because there is not a lot of links, no need to collapsable. Be careful of the fallback, it’s very important to have a link in the sidebar, related to the main README file. In the children array set the name of the files without the extension (.md). “label” and “selectText” are for the navigation (switch languages).

Create the directories (bolt, goody, otis) corresponding to the routes and inside of them markdown files named food and hobbies. You’ll see in the sidebar structure the title of these files.

Image for post
Image for post

Add also a directory named “fr” with the same directories names. All the directories have a README.md file having an introduction of the pet and two other markdown files presenting the hobbies and thefood.

Image for post
Image for post

Finally we add some pictures. You can find on this website.

Go inside each README.md file and add a title, a description and a picture.

The pictures are in the public directory (inside the .vuepress directory). We can reach them by putting a slash.

Image for post
Image for post
bolt/README.md
Image for post
Image for post

As you can see, we can put a HTML code, it’s convenient specially if you want to specify a size.

You can get all the texts in the repository.

Deployment

We will deploy with Netlify. Create an account.

Add your repository or drag & drop your project directory.

Image for post
Image for post
get your repository
Image for post
Image for post
drag and drop

You don’t need to create the dist directory, Netlify will create one by running the build command.

Add the settings :

Image for post
Image for post

Deploy !

Image for post
Image for post

Et voilà

Image for post
Image for post
Image for post
Image for post
The result

Conclusion

I hope this article was helpful. Feel free to explore VuePress. I really like this tool but if something is missing like a markdown file, there is no specific error, it’s just visual (e.g. the sidebar links not showing). As you can see you can deploy very quickly with Netlify.

You can follow me on twitter @Assitan_K.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store