# Exploring VuePress

Let's explore VuePress!

# Installation on Linux

We need node.js and yarn to run VuePress. Because yarn is not (yet) part of the officical Ubuntu package repository, we need to add a link to the yarn package that is maintained by the developers of yarn:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update
sudo apt install yarn

# Create a new documentation project

Often, VuePress is used in code projects that store all documentation inside a docs folder. Let's follow that convention. We create a project folder, a docs folder inside it and a simple markdown file:

mkdir new-project
cd new-project

mkdir docs
echo "# Exploring VuePress" > docs/README.md

# Add VuePress to the project

Now -- let's add VuePress to this project:

yarn init # Answer the questions.  I make sure to set 'private' to: true
yarn add -D vuepress

For build automation, add the following section to the package.json file (and make sure to put a comma after the previous section):

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

# Fix the reload bug

The current version of VuePress depends on a broken version of watchpack. Here is an active GitHub issue reporting this problem.

We add the following section to the package.json file to downgrade the dependency to an older verion --- that works:

  "resolutions": {
    "watchpack": "1.6.1"
  }

Again, make sure to add a comma after the previous section for correct json syntax.

We activate this bugfix with the following command:

yarn install

# View the documentation locally

Start the dev server with the following command:

yarn docs:dev

You can inspect the page at this URL: http://localhost:8080/

# Hot Reload for code changes

You can edit your documentation: When you save any changes, the dev server will detect the changes, rebuild the pages and notify the browser to reload them.

# Build the static pages bundle

Here is the command to build the static pages:

yarn docs:dev

The pages will be written to: docs/.vuepress/dist

These are the two pieces of information that we will need for automatic deploy.

# Automatic deploy with Netlify

  • Create a new repository for our project at Github, Gitlab or Bitbucket.
  • Push the first version of the project to the repository.
  • Sign up at https://www.netlify.com/
  • Click on the Sites tab, then New site from Git.
  • Follow the wizzard to connect to your git provider and select your repository.
  • Make sure to set the two basic build setting right:
    • Build command: yarn docs:dev
    • Publish directory: docs/.vuepress/dist
  • Click on Deploy site.

From now on, every new commit to the master branch of your repository will trigger an automatic build and deploy of your documentation.

# Some pointers to the documentation:

# The markdown source of this page

You can look at the markdown source of this page here.