published on August 3, 2018

vuepress version: 0.13.1

Vuepress is a wonderful static site generator created by Evan You the creator of Vuejs. The philosophy is of Vuepress is the same as Vuejs and can be resumed in one word: simplicity.

For now Vuepress is very good to generate documentation sites and as usual in the Vuejs ecosystem the documentation is the only thing you need to get started.

As I had to figure out how to connect the dots to use Travis, I decided to share to speed up the process of other adventurer.

Vuepress generates static websites that are simple html and js. They can be deployed in any static website host, cheap mutualised servers but also on GitHub. Vue press is a very good option to work as a team to generate documentation collaboratively. Pairing it with git and GitHub makes it easy to collaborate and track revisions. GitHub associated to Travis will allow the team not to worry on how to publish, but just to add documentation, push it and the rest is handled for them (us).

Additionally, GitHub can work as a (basic) CMS for your documentation as files can be created and edited there. Which can be very useful for a quick update or for less technical users that do not want to install, git and install a code editor on their computer.

Vuepress generates pages and navigation based on the content of Markdown files. Markdown is easy to learn and as a matter of fact all content editors in the company I work for use Markdown to publish on the web. It takes about 15 minutes to train them and handover and small cheat sheet.

For this setup, I suggest to have a repo to work on the documentation and a repo to which Travis will automatically publish the site every time there is a push on the `master` branch.

For that setup to work you will need:

A Travis account A GitHub account A working install of Vuepress

All other configurations are optional and let you add sidebars, top navigation, title of the project, etc.

The <publication-repo-name> is the path after github.com/<username || organisation name>/ . It will be used be need for the GitHub page to work. So yeah… Create two repositories:

The working repository The publication repository

On your computer create a folder that will host your project, go it to it and init a git project, we will create a minimal package.json file, .travis.yml to hold the Travis configuration, a .gitignore and a docs folder which will contain our Vuepress configuration and content. Then Link it to your working repository by adding the correct remote origin.

$ mkdir <folder name>

$ cd <folder name>

$ git init

$ touch package.json .travis.yml .gitignore

$ mkdir -p docs/.vuepress

$ cd docs/.vuepress

The resulting folder structure is:

└── <folder name>

├── docs

| └──.vuepress

| └── config.js

├── .gitignore

├── .travis.yml

├── package.json

└── README.md //optional

Vuepress is easy to install and all its configuration goes into a .vuepress folder. The only configuration that is needed for that project to work is to create at the root of that folder a config.js file that exports a module with the following content and any additional config that you wish for your project.

module.exports = {

base: ‘/<publication-repo-name>/’,

// ...

};

The package.json will hold:

{

"scripts": {

"docs:dev": "vuepress dev docs",

"docs:build": "vuepress build docs"

}

}

The docs:dev command will be used from <folder name> , the root of your project, to see the documentation site while you are working on it. It hot reloaded so when you save, you see your changes immediately

The second command will be used by our Travis script to generate our static site. Which we will configure now.

Open the .travis.yml file and copy the following:

language: node_js

node_js:

- "10"

env:

- CXX=g++-4.8 addons:

apt:

sources:

- ubuntu-toolchain-r-test

packages:

- g++-4.8

install:

- npm install -g vuepress

script:

- npm run docs:build

cache:

directories:

- "node_modules"

notifications:

email: false

deploy:

provider: pages

skip-cleanup: true

local_dir: docs/.vuepress/dist

github-token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable

repo: <username || or org name>/<publication repo name>

keep-history: true

target-branch: master

on:

branch: master

We first install nodejs 10 by default Travis installs an old version and it is not compatible with vuepress that requires nodejs ≥ 8. Then Vuepress is installed globally, we run the build script we configured before. We cache the node_modules like this the next build will be faster. I do not want to receive an email from every build, so I deactivated it here. If you want to get email remove it.

Then we deploy the result of the build. Notice that we take only the generated content in the dist folder. To publish to a repo we need a git token. We will do that next, but this is the variable name that we will use in Travis.

Then we set the repo to which we want to publish and on which branch. The keep-history property is very important. Without it you will have nothing to publish as Travis will have removed the files already. So yes, keep the files so that we could push it somewhere ;)

For the GitHub token, go to your Settings (Top right corner of the screen the drop down of your avatar), In the left hand side menu click on Developer Settings then on Personal Access Tokens . Create a new one. You can see it only once… So copy it and we will now set up Travis. If you did not get me, there is a step by step guide published by GitHub

Now on your Travis account we need:

Connect your Github account Activate your working repository

When this is done, go to your project settings:

You can find this in the More options drop down. You will see the following screen:

This is where you can create a new environment variable. Create a new one with the value GITHUB_TOKEN notice, no $ sign and in the value add the value of your newly created GitHub token. Make sure that the toggle is set as in the red box. This will hide the value of the variable in the build logs. It is important. If not you will give access to whom ever to your repository.

Final step, we need to configure the GitHub page. Go the settings of your publication repository:

Scroll down to the GitHub pages configuration and set:

Notice the source is the master branch and do you see the last segment of the path highlighted in red? this is the name of your repository and it is the base property that we have configured in the config.js file.