Create a simple i18n doc with VuePress

and deploy quickly with Netlify

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 :


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.

# config.js
module.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.

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.

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.

bolt/README.md

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.

get your repository
drag and drop

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

Add the settings :

Deploy !

Et voilà

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.