Introduction to the

Welcome to my guide on how to use VuePress! This project was born out of a desire to use VuePress as my blogging engine, and there was no clear path.

What is VuePress?

VuePress is a vUe-powered static website generator, a single-page application powered by Vue, Vue Router, and WebPack. In VuePress, you can write documents using Markdown and then generate web pages. Every page generated by VuePress has pre-rendered HTML, which is also very good for loading performance and SEARCH engine optimization. Meanwhile, once the page is loaded, Vue takes over the static content and turns it into a full single-page application, while other pages load on demand only as the user navigates through them.

version

The project is currently located at Version 0.11.0-beta.

purpose

The goal of the project is simple:

Record my whole process of using VuePress to build a blog, so that I can read and learn it in the future. At the same time, I hope to help you and provide you with a variety of choices. You can customize it according to your own preferences.

function

Why build a blog with VuePress? In addition to the great features that come with VuePress, you can use the following tools immediately:

  • Automatically generates the latest posts on the home page
  • Simple Google Analytics configuration
  • Automatic RSS feed generation
  • Simple icon configuration
  • A simple page on the home page
  • Archived pages for all posts are sorted by date

A piece of cake? So don’t waste any time, let’s get started!

An introduction to

To prepare

  • NodeJS >= 8
  • Yarn (Optional)
  • NodeJS and vUE basics
  • gitBash here

The installation

Install VuePress globally

Yarn Global add vuepress # or: NPM install -g vuepressCopy the code

Create a project directory

mkdir project
cd project
Copy the code

Initialize the project

Yarn init -y # or NPM init -yCopy the code

Create a New Docs folder

The docs folder serves as the root directory for project documents, and is used to house Markdown articles and.vuepress folders.

Create a new docs folder
mkdir docs

Go to the docs folder and create the readme.md file
echo '# Hello VuePress! ' > README.md
Copy the code

Set up the package. The json

There are two commands in VuePress. The VuePress dev docs command runs the local service, previews the website by visiting http://localhost:8080, and the VuePress build docs command generates static files. By default, Vuepress /dist. You can also change the default directory in the dest field in docs/.vuepress/config.js. To encapsulate the two commands as scripts, use NPM run docs:dev and NPM run docs:build.

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
Copy the code
  • Run the command at this point
npm run  docs:dev
Copy the code

Run and visit http://localhost:8080/,(at this time the page is blank with no content)

  • End the command and run the following command
npm run docs:build
Copy the code
  • View file changes with node_modules
  • Docs has a.vuepress file

Configure config. Js

# create config.js file in.vuepress
Add configuration information to config.js
module.exports = {
  title: 'Harold\'s blog', description: 'describe', head: [// inject the label [' into the current page link', { rel: 'icon', href: '/logo.png'}], ['link', { rel: 'manifest', href: '/logo.png'}], ['link', { rel: 'apple-touch-icon', href: '/logo.png'}],], serviceWorker: true, // Enable PWA base: '/VuePress/', // deploy to Github related configuration markdown: {lineNumbers: true // code block whether to display line number}, themeConfig: {// navigation bar configuration nav:[{text: 'Home', link: '/' }, {text: 'Learn', link: '/learn/' }, {text: 'Profile', link: '/profile/' }, {text: 'vue', link: '/vue/' }, {text: 'react', link: '/react/' }, {text: 'Our law', link: '/ Wind, flower, snow and moon /' } ], version: '0.11.0 beta -'}}Copy the code
  • The base path of the base site, whose value should always start and end with a slash. Set to/VuePress/here, and we once again running locally, the access path will need to change to http://localhost:8080/VuePress/
  • Title The title of the site
  • Description Specifies the description of the site

Run the project

npm run  docs:dev
Copy the code

(as shown in figure)

The deployment of

The last step is to deploy the GitHub Pages to the server. For details, please refer to Vupress- Deployment. Of course, if you have your own server, you can also try to deploy it on your own server.

Create the Github repository

  • Create a repository and submit your code to Github.
  • indocs/.vuepress/config.jsSet the correct base in the file. The base path for deploying your site, which you will need to set if you want your site to be deployed to a subpath. Like GitHub Pages, if you want to deploy your website tohttps://foo.github.io/bar/, thenbaseShould be set to"/bar/".

Automatic deployment

In the project root directory, create the following deploy.sh script file (uncomment the highlighted lines at your discretion) :

#! /usr/bin/env sh # Make sure the script throw encountered error set -e # generate static file NPM run docs:build # enter generated folder CD docs/.vuepress/dist # if published to custom domain name # echo 'www.example.com' > CNAME git init git add -a git commit -m 'deploy' # https://<USERNAME>.github [email protected]:<USERNAME>/<USERNAME>.github. IO. Git master # If published to https://<USERNAME>.github [email protected]:<USERNAME>/<REPO>.git master:gh-pages cd -Copy the code

Add in the dependency package.json file

{
  "scripts": {
    "deploy": "bash deploy.sh"
  }
}
Copy the code
  • Double click on thedeploy.shRun the script or project root folder right click gitBash here and type bash deploy.sh to automatically deploy to our GitHub repositorydeploy.shConfigured in the filemaster:gh-pagesbranch

Making operation

  • Finally, open Github, click the Setting button in the Github project, go to github pages-Source, select the GH-Pages branch, click the Save button, and quietly wait for it to complete deployment.

Hit the pit

  • When I did everything correctly, I still didn’t place the project on GitHub Pages

  • Dig a hole:deploy.shThere’s a pit in the file at the end of the pushgit push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pagesThis is fine if your project was cloned using SSH, but unfortunately I cloned it using the simple and familiar HTTPS,
  • Pit filling: After configuring SSH, clone the project using SSH again. Double-click deploy.sh to deploy the project automatically

Configure SSH

Git user name and email

If you are using it for the first time or have not configured it before, you need to run the command and replace the corresponding fields yourself.

git config --global user.name "harold1024"
git config --global user.email  "[email protected]"
Copy the code

Check whether the SSH Key exists

SSH ls // Check whether the id_rsa and id_rsa.pub files exist. If yes, SSH keys existCopy the code
  • Ls lists all files to see if there are id_rsa and ID_rsa_pub
  • Skip the key generation step if yes

Generate a key

ssh-keygen -t rsa -C "[email protected]"
Copy the code

Obtain the SSH Key

Cat id_rsa.pub // Copy the secret key ssh-rsa startsCopy the code

Add an SSH Key to GitHub

  • GitHub click on the user’s profile picture and select Setting
  • Select SSH and GPG keys on the left
  • Create an SSH Key
  • Give it a name, copy the secret key you copied earlier, and add it.

Verification and modification

Test whether the SSH Key is configured successfully

SSH -t [email protected] // The following command output is displayed: Hi harold1024! You've successfully authenticated, but GitHub does not provide shell access.Copy the code

In Clone or Download, switch Use HTTPS to Use SSH.