# VuePress Tutorial 3 - Set Up and Installation

By: Jay the Code Monkey

•Posted: Jan 16, 2022 •Updated: Apr 18, 2023

# Setting Up and Using GitHub

First we'll be going over how to create a repository on GitHub (opens new window). If you plan on using these tutorials as guides and want to start your own project from scratch, then you should create your own repository.

Each tutorial in this series involving code will also have a branch in the code-monkeys-blog-tutorials (opens new window) repository. If you want the code for a specific tutorial, then you can download a specific branch or clone the repository and switch to one of the remote-tracking branches. We'll go over how to download and clone the code in more detail in the sections below.

You can also download, clone, or fork the current version of the code-monkeys-blog (opens new window).

If you don't have git installed, then check out the Installing Git (opens new window) documentation. Also, if you don't have a GitHub account, then Join GitHub (opens new window) and Set up Git (opens new window).

# Creating a Repository

A repository is a directory where you store the code and other files used in a project. A repository can be a local directory on your computer and can be stored and accessed online from a website like GitHub (opens new window).

If you want to create your own repository for your own project, then you need to:

Go to your profile page, click on the Repositories tab, then click the New button or on any page in the upper right corner, click the + drop-down menu, then select New repository
Type a short and descriptive name in the Repository name field
Type a description in the Description field (optional)
Choose if you want the repository to be Public or Private
Add a README.md file which you can use to describe your project in more detail and to document how to install and use your project
Add a .gitignore file which is used to ignore specified files and directories when making a commit, I recommend selecting the Node template from the drop-down menu
Add your preferred license which is used to tell others how they can use your code
You can also choose a different default branch name, e.g., master instead of main by clicking on the settings link
Click the Create repository button

If you run into any issues when creating the repository or want to learn more, then check out the Create a Repo (opens new window) documentation. If you need help determining which license you should use, then check out Choose a License (opens new window). You can also learn more about the .gitignore file from the gitignore (opens new window) documentation.

After successfully creating your repository, you can now clone it to make a local copy on your computer.

# Cloning a Repository

To clone your newly created repository, you need to:

Go to the main page of your repository
Click the Code button and select your preferred method to clone the repositroy, e.g., SSH
Copy your preferred remote URL
Replace the example URL below with your copied URL, then run one of the following commands in your preferred directory:

If you run into any issues when cloning the repository or want to learn more, then check out Cloning a Repository (opens new window) and About Remote Repositories (opens new window).

The next sections will show you how to download and clone the code from the code-monkeys-blog-tutorials (opens new window) repository.

# Downloading Tutorials from GitHub

If you want to download the code for a specific tutorial, then you need to:

Go to the code-monkeys-blog-tutorials (opens new window) repository
Select which branch you want to download, e.g., tutorial-3
Click the Code button and select Download ZIP
Save the ZIP file to your preferred directory
Unzip the file in your preferred directory

# Cloning and Using Tutorials from GitHub

If you want to clone the tutorials, then you need to run one of the following commands in your preferred directory depending on your preferred method:

If you run into any issues when cloning the repository or want to learn more, then check out Cloning a Repository (opens new window) and About Remote Repositories (opens new window).

After successfully cloning the repository, you can run the following command to list both the remote-tracking and local branches:

Before switching to one of the remote-tracking branches, run the following command to get all of the latest changes from the remote repository without modifying your working directory:

Now, to work on the code for a remote-tracking branch you need to make a local copy of it which you can do by running the following command:

If you get an error when running the above command and the provided branch name exists, then check your version of git by running git --version. You need to be using at least Git 2.23 (opens new window) to use the switch command.

If you have an older version of git or if you prefer to not use the switch command, you can alternatively run the following command to work on the code for a remote-tracking branch:

The recommended way to switch branches is with the switch command since the checkout command does more than just switching branches which can lead to confusion.

If a remote-tracking branch is updated and you want to integrate those changes into your local branch, then switch to the branch you want to update and run the following command:

If you edit the code for a branch and attempt to pull, you may run into merge conflicts. You can check out About Merge Conflicts (opens new window) to learn more about what they are and how to resolve them.

# Dependencies

Before installing VuePress (opens new window), you first need to have Node.js 10+ (opens new window) installed and optionally Yarn 1 (opens new window).

It's recommended to use Yarn 1 (opens new window) if either one of the following applies to you:

You're using webpack 3.x (opens new window) in which case you may notice installation issues with npm.
You're going to be closely following along with these turtorials in which case I recommend using v1.22.17 since it's the same version being used by the Code Monkeys Blog. This will allow you to avoid any potential issues with packages and with the GitHub Actions (opens new window) workflow which is used when deploying the site.

Using the Locally Set Version of Yarn in the Repositories

The code-monkeys-blog-tutorials (opens new window) and the code-monkeys-blog (opens new window) repositories both have a local version of yarn set to v1.22.17 in a .yarn/releases directory. This means if you use the code from the repositories, then you'll be able to use the locally set version of yarn instead of having to install the specific local version of yarn yourself.

The next sections will show you how to check your current versions of node and yarn.

If you don't have node or yarn installed or you want to change the versions, then check out the provided resources explaining how to install specific versions.

# Checking Node Version

To check if you have node installed run the following command:

If you see an output of v10.xx.xx or greater, then you can continue on with the VuePress (opens new window) installation.

Code Monkeys Blog Node Version

The Code Monkeys Blog is currently using Node.js v16.11.1 (opens new window). If you're going to be closely following along with these turtorials, then I recommend using the same version to avoid any potential issues.

If you don't see the proper output or want to use the same version in these tutorials, then you need to either install or upgrade node.

To install a system version of node you can go to Node.js (opens new window) and download a compatible version.

If you previously installed a system version of node from Node.js (opens new window), then you can go back to the site and download a newer version to upgrade your current version.

If you're a developer that needs to use multiple versions of node when working on different projects, then I recommend using a node version manager. Before installing a node version manager like nvm (opens new window) or fnm (opens new window), I recommend uninstalling your system version of node, npm, and any globally installed npm packages to avoid potential issues.

Check out these posts Installing Node Version Manager (nvm) and Installing Fast Node Manager (fnm) to learn how to install and use them.

Preferred Node Version Manager

My preferred way to manage my node versions is with fnm (opens new window) since it's much faster than nvm (opens new window).

After installing a compatible version of node, you will now have npm the default package manager for node. If you prefer you can use npm to install VuePress (opens new window). However, if you're going to be closely following along with these tutorials, then I recommend using yarn.

# Checking Yarn Version

To check if you have yarn installed run the following command:

If you don't see your preferred version of yarn, then it's recommended to install or upgrade a global version of Yarn 1 (opens new window) which can then be used to set a local version of yarn for the project.

To learn more about how to install a global version of Yarn 1 (opens new window), how to use the global version to set a local version of yarn for a project, and other commonly used commands check out the Installing Yarn 1 post.

If you created your own repository and are using a locally set version of yarn, then be sure to update your .gitignore file and add a .gitattributes file as described in the Installing Yarn 1 post.

Recommended Version and Repositories Reminder

Remember the recommended version of yarn to use with your project if you're closely following along with these tutorials is v1.22.17. Also, if you use the code from the repositories, then there will be a provided local version of yarn which you can use instead of installing the specific local version yourself.

# Installing Tutorial Packages

If you downloaded or cloned the code from the code-monkeys-blog-tutorials (opens new window), first check your version of yarn by running the following command in the project directory:

If the version of yarn is v1.22.17, then you can install all of the packages being used in the project by running the following command in the root project directory:

Make sure you're not using the master branch when checking the version since it doesn't have the .yarn directory and that you have a global version of yarn installed.

If you're using your own repository and want to install VuePress (opens new window) yourself, then use one of the installation methods described below.

# Installing VuePress

When installing VuePress (opens new window) you have the option to use the create-vuepress-site generator (opens new window) for a quick start installation or a manual installation. We'll go over both of the installation methods, but the future tutorials will be based off of the manual installation.

# Quick Start

Using the generator will help scaffold a basic site structure for you by creating common directories and files found in VuePress (opens new window) sites.

To use the generator run the following command in your preferred directory using your preferred package manager:

After running the above command, you'll be asked to answer some questions. You can enter custom values for each question or press enter to accept any defaults. Here's an example of running the command in a directory named quick-start-project:

The scaffolded basic site is created in a docs directory in your current directory which in the example above was quick-start-project. All of the created directories and files are listed above.

If you're using npm you'll see a .npmignore file in the docs directory instead of a .gitignore file.

Using an Optional Directory Name

If you passed an optional directory name, then the scaffolded basic site is created in the given directory in a docs directory.

The answers given to the questions can be found in the docs directory in the package.json file which contains your site's metadata.

Here's the contents of the package.json file from the example above:

We'll be covering the contents of the package.json file in the next tutorial. If you're interested in learning more now, then check out the package.json guide (opens new window).

To see your newly created site, navigate to the docs directory:

Install your site's packages using your preferred package manager:

Installing the Same VuePress Version

The above command will install the latest version. If you want to install the same version being used in the tutorials and blog, then run yarn upgrade vuepress@1.8.2.

Start the hot reloading local development server:

Your site should now be running at http://localhost:8080/ (opens new window).

# Manual Installation

The manual installation method allows you to start building your site from scratch unlike the quick start method which scaffolds a basic site structure for you.

As mentioned above, the following tutorials will be based off of the manual installation method.

Using an Existing Project

If you already have an existing project and you would like to keep the documentation inside of it, then start from the third command.

Navigate to your preferred directory which should be where you cloned your site's repository:

Initialize your project with your preferred package manager:

After running the above command, you'll be asked to answer several questions. You can enter custom values for each question or press enter to accept any defaults. Here's an example of running the command in a directory named project-directory:

After answering all of the questions, a package.json file containing the answers is created. The package.json file is used to describe metadata about your site.