楼窗晚风

烟霭也似的遐思和怅惘。

  1. 1. How to Build a document site by Vuepress
    1. 1.1. Environments
      1. 1.1.1. Node.Js
      2. 1.1.2. Yarn
      3. 1.1.3. Git (Optional)
    2. 1.2. Setup Vuepress
      1. 1.2.1. Create a Github repo for deploying Vuepress
      2. 1.2.2. Install Vuepress
      3. 1.2.3. Basic configuration for vuepress
      4. 1.2.4. config.js
      5. 1.2.5. root README.md
      6. 1.2.6. Add navigate links
      7. 1.2.7. Start writing
      8. 1.2.8. Summary
    3. 1.3. Deploy
      1. 1.3.1. Create deploy script

How to Build a document site by Vuepress

Before the beginning, I’d like to answer a question: Why you write this tutorial?

Yeah, there’s too many others article like this, but most of them assume that you have already learned Vue.js and had some knowledge of website building and deploying. So that’s why I make this article: for people who don’t know what is vue.js and never had a website. Anyway, it’s not a zero-basic tutorial, at least, you should know about some things like what is GitHub? why should I write a document?

Environments

This tutorial based on Windows 10 platform, and all the examples are under the windows-style.

Node.Js

Access the official website of Node.js, as you can see, there are 2 green buttons, we should click the left one: LTS version of Node.js

image-20210605211258441

When it finished, you can see a .msi file like this one:

image-20210605211512722

Double click to open it, and keep clicking the Next button until the install wizard shows a Finish button. Since then, we installed node.js.

Yarn

Although npm(node package manager) provides all the features, according to the document of the vuepress, yarn would be a better choice than npm.

Let’s access yarn installation site, expand the Alternatives section:

image-20210605212346019

Click the Download Installer Button, after the progress running over, you can get a .msi file, install it like node.js installer.

Git (Optional)

This step is optional, but if you do this, your work will be much easier.

Access git official website, you can see the interface like this:

image-20210605213126512

Click the button that I marked with a red box, the download will be starting, after then, you will get a git installer executable file, start it and just keep the default configuration.

If install succeeds, you will see 2 git menu in any context menu of windows explorer:

image-20210605213804014

As you can see, I marked Git Bash, which is the command terminal we need to instead of windows cmd or Powershell.

Setup Vuepress

Now, we had node.js and yarn, we are ready to start building a vuepress site!

Create a Github repo for deploying Vuepress

I won’t show how to create a GitHub repo, but I would notice you are:

image-20210605214554406

You should choose the .gitignore template to Node, it will be more convenient for you.

Clone the repo that we just created to the local disk, enter the directory that you contains your repo, and open git bash for it.

Install Vuepress

Before work starts, input the command below:

yarn init -y

This command means we created a node package with the default configuration. Then we can add vuepress to dependencies of our package:

yarn add -D vuepress

This command needs about 2 minutes to complete, keep your patience.

image-20210605215211625

Since then, we installed the vuepress local.

Basic configuration for vuepress

After you installed the vuepress, the structure of your local files should be like this:

image-20210605215450501

Open the package.json, add these lines in this JSON file and append .temp in the .gitignore file

"scripts": {
	"dev": "vuepress dev docs --temp .temp",
	"build": "vuepress build docs"
}

This step is also optional, but if you do this, your progress will be more convenient. In fact, you don’t even need to know what these commands used for, just follow the steps.

Now we created a folder that must named docs,

image-20210605220029939

Then we created a file named README.md (just like index.html if you have any website knowledge), write any content you want inside.

image-20210605220202704

Since here, we could serve a local server for our document side, just input this command:

yarn dev

When this interface displayed, your local document server has been created.

image-20210605220517338

Access http://localhost:8080, you can see an empty vuepress side now:

image-20210605220600598

config.js

Create a folder named .vuepress in /doc:

image-20210605220743591

Create a javacript file in /.vuepress:

image-20210605220912318

Add these lines inside:

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around',
  base: "/Vuepress4Beginner/"
}

There’s a point you should be noticed, the base key should appear when you trying to deploy your document site on a sub-directory like http://www.xxxx.com/xxxx, the slash symbol should be beginning, and the end.

Restart your local server, you will see the host had appended your base value

image-20210605221808225

And you will see the effect of the config.js, a title element displayed in the top-left corner

image-20210605221900646

root README.md

Add these lines at the top of root README.md:

---
home: true
herImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

You can change the element content as you want, the hereImage key should be removed if you don’t need it. And if you need a big logo on your document home page, you should know some basic knowledge about vuepress asset.

The content below the YAML font matter will be display as normal markdown content.

Now, I’ll tell you what is ever YAML font matter key-value pair used for:

  • home: this page is used for the home page or not
  • heroImage: the main logo displayed in the center of the home page
  • heroText: the main title displayed in the center of the home page
  • tagline: the subtitle under the heroText
  • actionText: the text for the central button
  • actionLink: the jump target for central button
  • features: some feature under the central button
    • title: feature title
    • details: feature description
  • footer: the text display in the footer of the site

image-20210605223618117

Open config.js, and add these lines:

themeConfig: {
  nav: [
    { text: 'Home', link: '/' },
    { text: 'Guide', link: '/guide/' },
    { text: 'External', link: 'https://google.com' },
  ]
}

As you can see, there’s an array named nav, you can add its member like:

{ text: 'Home', link: '/' }
  • text: the text display in navigate bar
  • link: the link for navigating, you can use a relative or absolute URL

If you would like to know about the navigation bar, you can visit navbar links in vuepress document.

Start writing

After all of these configurations, now you can start to write documents via markdown.

Create a folder named guide in /docs:

image-20210605223831721

Create a README.me in /docs/guide

image-20210605223942377

Add this YAML font matter at the top of this README.md:

---
sidebar: auto
---

Enjoy!

image-20210605224226895

Summary

This is how the document site looks like after the above configurations,

image-20210605225004660

I’ll list some point that you maybe didn’t know:

  • REAME.md equals to index.html in website building
  • The local file structure of our example:
    • .temp
    • docs
      • .vuepress
        • config.js
      • guide
        • README.md
      • README.md
    • node_modules
    • .gitignore
    • package.json
    • yarn.lock

Deploy

After all the work above, now we can deploy our document site to GitHub pages, maybe you would like to try another deployment, so you can check out vuepress document.

Create deploy script

Create a .sh file named deploy.sh in the root directory

#!/usr/bin/env sh

# abort on errors
set -e

# build
npm run build

# navigate into the build output directory
cd docs/.vuepress/dist

# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if you are deploying to https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# if you are deploying to https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

I’d like to recommend that you shouldn’t just push the static pages to your master branch, your master branch should be storage your development environment. So you can just push them to another branch.

Since then, you should add this line in the config.js:

"deploy": "bash deploy.sh"

And then config.js should look like:

image-20210605231251492

As you can see, we are using the windows operating system, but there’s a bash command that’s didn’t exist in windows. How to solve this? The answer is: we don’t even need to solve because we are using git bash. That’s why I recommended you to choose git bash but not the windows cmd or Powershell.

Now, just run

yarn deploy

Then, turn to GitHub, open the repo for hosting the vuepress document, turn to the Setting page:

image-20210605231615793

And go to the Pages section, set the source branch to gh:pages, click save. Just wait for moments, then access your page.

image-20210605231713557

Congratulations! You’ve done all the work!

Author : AHpx
This blog is under a CC BY-NC-SA 3.0 Unported License
Link to this article : https://sinoahpx.github.io/2021/08/27/How%20to%20build%20a%20document%20website%20via%20Vuepress/

This article was last updated on days ago, and the information described in the article may have changed.