This article focuses on building a technical document with VuePress, which is associated with Github Pages. This is what we often see below:

The final effect is shown below:

If that’s what you want to do, read the following carefully.

Important note

This article will not repeat the contents of the official documentation; the API on the official website is well written and detailed. So, please follow the instructions on the official website step by step, if you encounter other problems, the content of this article may help you. Go to the website

background

At the beginning, I did not intend to build a technical document directly. Our team first developed a set of quick application UI component library quist-UI. In order to facilitate developers to read, WE finally decided to build it with Vuepress. Therefore, the installation method I use is consistent with the existing project installation introduced on the official website.

My project started as a quick application project architecture, webpack version 3.12.0.

start

When installing with an existing project, I had a weird problem with the NPX vuepress dev docs command and kept getting an error. If this happens to you, try installing YARN Global add vuepress or NPM install -g vuepress globally.

The directory structure

There are two special points, I also spent some time in the configuration.

1. The picture of the home page (in this case, the picture of the white pigeon)

Open the readme. md file in the docs folder and refer to the instructions on the official website.

heroImage: /quistUI.png
Copy the code

For this configuration, you need to create a new public folder under the.vuepress folder and put the image here so that it will be automatically packaged when it is packaged.

2. The small icon on the left of the browser

You need to configure it in the config.js file, refer to the instructions on the official website. So in my project, it’s a little bit different from the official website, href /.

# My project
head: [
    ['link', { rel: 'icon', href: 'favicon.ico'}]]# website
head: [
    ['link', { rel: 'icon', href: '/logo.png'}]]Copy the code

These two images need to be placed in the public folder ~

Upper navigation page

Refer to the instructions on the official website.

The left navigation

Refer to the instructions on the official website.

At this point, your technical documentation should be available locally, and finally, deployment.

The deployment of

Refer to the instructions on the official website.

As mentioned above, my project is deployed on Github, so I will only say how github is deployed and only say where it differs from the official website.

Deployment is divided into two steps:

  1. Create in the project root directorydeploy.shFile, andpackage.jsonIt’s at the same level.
#! /usr/bin/env sh
Make sure the script throws any errors it encounters
set -e

Generate static files
npm run docs:build

Go to the generated folder
cd docs/.vuepress/dist
# git init () # git init () # git init (

The following line is not available on the official website, if you are a multi-player development project, you must execute this command
git pull https://github.com/JDsecretFE/quist-ui.git master 
git add -A
git commit -m 'deploy'
git push -f https://github.com/JDsecretFE/quist-ui.git master:gh-pages

cd -
Copy the code

Open the package.json file and add the command scripts as shown below:

"deploy": "bash deploy.sh"
Copy the code

  1. Log in to Github, go to Settings -> Github Pages, select the GH-Pages branch, and save.

Now let’s open the command tool and look at our branches. There should be a master branch and a GH-Pages branch (if not, create one yourself). We execute NPM run deploy on the master branch, and docs/.vuepress will add a dist folder where we need all the stuff we need.

Finally, we copy the contents of dist folder in master branch to GH-Pages branch, complete.

If you have a better way, please reply to me, thank you.

Please refer to the docs project structure under this heading. If help you, please give a star encouragement ~~~