preface

Only heard of Vue, never heard of Vuepress? It’s part of the new VUE Family bucket, the Mighty Rain Creek, which launched on April 12, 2018. Don’t believe it? See Evan You Github. Star number has exceeded 10,000. Vuepress is a quick and easy way to build technical documentation websites and personal blogs. Let’s start learning with me! (If you want to do coding directly, you can start from section 3.)

I. Module overview

Definition 1.

Vue – driven static web site generator

Highlight 2.

The advantages of Vuepress summarized by myself

3. Horizontal comparison of similar modules
Nuxt:

  • Nuxt: Nuxt can theoretically do what VuePress can do, but Nuxt was built to build applications

  • VuePress: Focuses on a static, content-centric web site with out-of-the-box features customized for technical documentation

Docsify / Docute:

Both are VUe-based, however they are fully run-time driven and thus not SEO friendly

  • Hexo:

The theme system is too static and relies too much on pure strings rather than Vue based. Also, Hexo’s Markdown rendering configuration is not the most flexible

GitBook:
  • When there are many files, the reload time after each edit is unbearably long
  • The default topic navigation structure is also somewhat restrictive
  • The theme system is also not Vue driven
  • The GitBook team is more focused on making it a commercial product than an open source tool

Second, finished product display

1. Technical documentation Website:

Vue family bucket official website: VUE, vuex, VUE-CLI, vue-Router and vuepress itself

2. Personal Blog:

Blog 1 (default theme), Blog 2 (custom theme)

Three, start building

Before coding, it is recommended that you understand markdown syntax to prepare for later documentation: portals

1. Install VuePress globally

npm install -g vuepress

2. Create and enter the project

mkdir vuepress-demo && cd vuepress-demo

3. Initialize the project

NPM init -y // The default configuration is yes

Add the following two startup commands to the generated package.json: "scripts": {"dev": "vuepress dev docs", "build": "vuepress build docs"}Copy the code
4. Create the basic project structure
There is only a recommended directory structure, and no CLI is available, so you need to create the following structure either on the command line or manually: Vuepress - demo ├ ─ package. Json ├ ─ docs | ├ ─ README. Md | ├ ─. Vuepress | | ├ ─ config. Js | | ├ ─ public | | | └ avatar. PNG | | | ├ spider. PNG contains files with a suffix, folders withoutCopy the code
5. Configuration config. Js

This file is the most important configuration file for the project, where almost all configuration items are performed. Let’s start with the simplest configuration to see how it works:

Module. exports = {title: 'exports ', head: [// exports <head> tags ['link', {rel: 'icon', href: '/avatar. PNG '}], // add a custom favicon [themeConfig: {logo: '/avatar. PNG ', // top left logo: [// navigation bar configuration {text: 'front page' link: '/'}, {text: 'technical documentation, link:'/tech/interview/'}, {text: 'Jane books home page, the link: 'https://www.jianshu.com/u/c455567c7f50'}], sidebar: 'auto', / / the sidebar configuration}};Copy the code

If you want to see the detailed configuration, please refer to the official website -config configuration. Note: The root path of the route is the docs folder, and the root path of static resources (images) is the public folder

6. Start the project

NPM run dev default service started at http://localhost:8080/, the effect is as follows: Demo version 1 we configured the title, nav, sidebar, logo are all effective! Congratulations, you’ve completed your first minimal demo! The official default theme used here:

  • Logo and title in the upper left corner
  • The global search box and nav navigation bar in the upper right corner
  • Sidebar navigation bar on the left (automatically sets MD level 1 title as navigation copy)
  • Markdown content on the right

Note: The project comes with hot updates; However, config.js may sometimes fail to hot update, requiring a restart of the project

7. (Optional) Configure the home page.

The average technical documentation site will need a front page to introduce the technology, and personal blogs will need such a welcome page.

-- Home: true heroImage: /spider. PNG heroText: My homepage Markdown-centric project structure, with minimal configuration to help you focus on writing. - Enjoy the development experience of Vue + Webpack, use Vue components in Markdown, and use Vue to develop custom themes. - Title: High performance Details: VuePress pre-renders static HTML for each page and runs as SPA when the page is loaded. Footer: Front-end old bird personal blog --Copy the code

The effect is as follows:

8. Change the subject (optional)
  • Change the theme:

Not happy with the default theme and looking for a different theme? Arrangement! Set in config.js:

module.exports = {
  theme: 'vuepress-theme-xx'
}
Copy the code

You can find your favorite theme in NPM, where the theme starting with @vuepress/theme- is the official maintenance theme:

  • Development Theme:

No suitable theme on NPM? Arrangement! Then let’s develop a theme, length reasons do not introduce details, interested students can check the official document – development theme

  • Change the default theme:

Hate to go to the trouble, but the default theme doesn’t meet your needs? Arrangement! Make some changes to the default theme to suit your needs. To release the functional components of the default theme, run the following command:

vuepress eject docs
Copy the code

You’ll notice that under the root directory, there’s a theme folder like this:

9. Using vUE components in MD files (optional)

The MD file in the Vuepress project can be used directly with the VUE component. We can create a components folder under the.vuepress folder, where vue components are automatically registered globally as follows:

10. Client enhancements (optional)

If you want to make some improvements to your application, such as using router for login blocking, mounting global variables to vue instances, or registering other components, you can create a new file enhanceapp.js under.vuepress:

Export default ({Vue, // Vue constructor options being used by VuePress, // some options attached to the root instance router, SiteData => {//... Do some other application-level optimizations}Copy the code

This file is similar to the main.js file in vue-CLI scaffolding

Iv. Deployment online

Through the above work, we have mastered the basic usage of Vuepress, you can fill more MD files to enrich your web page. But it’s all local. To make your site accessible to everyone over the Internet, you need to apply for a domain name and a server and deploy your project:

1. Select your server

There are two kinds of server, free and charge, each has its advantages and disadvantages:

  • Free:

Use Github Pages. Github is a static site hosting service for personal websites. Many people use it to build personal blogs. The advantage of this method is that it is free and convenient, but the disadvantage is that the speed may be a little slow and cannot be included by domestic search engines.

  • Charges:

Domestic do better cloud services are Ali Cloud, Tencent cloud, the advantage is guaranteed speed, can be included by the search engine, the disadvantage is to spend money, tuhao please ignore. Here we choose plan 1

2. Create a repository on Github
  • Log on to making
  • Create a new repository: username. Github. IO

(It must be your Github username, not your nickname)

  • Create warehouse 2, named as vuepress-demo

The relationship between the two is: warehouse 1 is responsible for displaying the content of the website, we don’t need to change it; Daily development and additions are in Repository 2, and the code is published to Repository 1 using the NPM run deploy command

3. Associate the local project with the Github repository
Git remote add Origin git remote add origin git remote add origin git remote add origin git remote add origin git remote add origin [email protected]:nieyulin112/vuepress-demo.gitCopy the code
4. Create a deployment file
  • Create deploy.sh in the root directory.
#! /usr/bin/env sh # Make sure the script throw encountered error set -e # generate static file NPM run build # enter generated folder CD docs/.vuepress/dist # if published to custom domain name # echo 'www.yourwebsite.com' > CNAME git init git add - A git commit -m "deploy" # if you want to deploy to https://USERNAME.github.io git push -f https://github.com/nieyulin112/nieyulin112.github.io.git master # if released to https://USERNAME.github.io/ < REPO > # git push -f [email protected]:USERNAME/<REPO>Copy the code
  • The root directory creates readme.md

This file is for your project description or usage. Git projects usually have this file. It has nothing to do with the md file in your project.

5. Git commits
Before you commit to git, make sure that you have logged in to your local git account. Otherwise, you have no permission to commit to the remote device. If you are not logged in locally, refer to git's First Login tutorial. Alternatively, a.gitignore file can be added to the root directory to prevent unnecessary commits: Git commit -m 'basic setup completed' git push --set-upstream origin master Check your Github repository and find that it has been uploaded successfully:Copy the code
6. Create the deploy command and execute it
Json: "scripts": {"deploy": "bash deploy.sh"} NPM run deployCopy the code
7. Successful release!

Check out your blog domain: nieyulin112.github. IO/So everyone can visit your blog!

8. PWA (optional)

PWA, or Progressive Web Apps, gives you the experience of native apps in the form of the Web. VuePress supports PWA by default. The configuration method is as follows:

Config.js add configuration: head: [// Inject tags into the HTML <head> of the current page ['link', {rel: 'manifest', href: '/photo.jpg'}], ['link', {rel: 'apple-touch-icon', href: '/photo.jpg' }], ], serviceWorker: Json file in PWA public folder and add: {"name": "start_url", "short_name": "start_url": HTML, display: standalone, background_color: "# 2196F3 ", description: "theme_color": "blue", "icons": [ { "src": "./avatar.png", "sizes": "144x144", "type": "image/png" } ], "related_applications": [ { "platform": "web" }, { "platform": "play", "url": "Https://play.google.com/store/apps/details?id=cheeaun.hackerweb"}}] redeploy: NPM run the deployCopy the code

Personal blog