Preface:

VuePress is a project written by UTTU to support the documentation requirements of Vue and its sub-projects. The VuePress interface is very simple and easy to use. The project architecture can be put together in an hour. There are a lot of these types of documents out there, and if you need to write technical documentation for a project, VuePress is definitely an option for you.

Swimming, fitness learn about: blog, front-end accumulation document, public account, GitHub

VuePress features:

  • Built-in Markdown extensions optimized for technical documentation
  • The ability to use Vue components in Markdown files
  • Vue driven custom theme system
  • Automatically generates a Service Worker
  • Google Analytics integration
  • Git based “Last Updated”
  • Multilanguage support
  • Default themes include:

I suggest you look at the official document first

Effect:

Maybe you build a document that looks like this:

Build:

Install VuePress globally

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

New folder

You can manually right-click to create a folder, or you can use the following command to create a folder:

mkdir project
Copy the code

Project initialization

Go to the project folder and initialize the project using the command line:

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

This creates a package.json file that looks like this:

{" name ":" the project ", "version" : "1.0.0", "description" : ""," main ":" index. Js ", "scripts" : {" test ", "echo \" Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }Copy the code

Create a new docs folder in your project root directory:

This document will be used as the root directory of the project document:

mkdir docs
Copy the code

Create it in the Docs folder.vuepressFolders:

mkdir .vuepress
Copy the code

All vuepress-related files will be stored here

in.vuepressFolder belowconfig.js:

touch config.js
Copy the code

Config.js is the necessary configuration file for VuePress, which exports a javascript object.

You can start by adding the following configuration:

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}
Copy the code

in.vuepressCreate public folder below:

mkdir public
Copy the code

This folder is used for static resources, and when packaged it will be placed in the root directory of.vuepress/dist/.

Home page (like the VuePress documentation home page)

Create a readme.md in the docs folder:

The default theme provides a home page. Set home: True as below. You can put the following Settings into readme.md and you will see the same home page as VuePress.

-- home: true heroImage: /logo.jpg actionText: Quick Start → actionLink: /zh/guide/ features: - title: Details: details: A Markdown-centric project structure helps you focus on writing with minimal configuration. -Title: Vue Driver Details: Enjoy the development experience of Vue + WebPack, using Vue components in Markdown, while you can use Vue to develop custom themes. -Title: High performance Details: VuePress generates static HTML for each page pre-render and runs as a SPA when the page is loaded. Footer: MIT Licensed | Copyright © 2018 - present Evan You -Copy the code

Ps: You need to put an image in the public folder.

Our project structure is in place:

Project ├─── docs │ ├── readme.md │ ├─.vuepress │ ├─ public │ ├─ config.js │ ├─ ch.htmCopy the code

inpackage.jsonAdd two start commands to the

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
Copy the code

Start your VuePress:

The default is localhost: port 8080.

Yarn docs:dev # or: NPM run docs:devCopy the code

Construction:

Build generates static HTML files, which by default are in the.vuepress/dist folder

Yarn docs:build # or: NPM run docs:buildCopy the code

Basic configuration:

The most standard, of course, is the official document, which can be configured to your own requirements.

Take a look at my config.js configuration:

Module. exports = {title: 'title ', description:' description ', // inject the HTML <head> tag into the current page head: [['link', {rel: 'icon', href: '/favicon.ico'}], // add a custom favicon [/favicon.ico], base: Markdown: {lineNumbers: true // code block displays line number}, themeConfig: {sidebarDepth: 2, // e'b will extract both h2 and H3 headers from Markdown and display them in the sidebar. LastUpdated: 'Last Updated' // update time: git Last committed}};Copy the code

Navigation Configuration:

Module. exports = {themeConfig: {nav:[{text: 'front end algorithm ', link: '/algorithm/'}, // internal link to docs {text:' blog ', link: {text: 'GitHub', items: [{text: 'GitHub', link: 'https://github.com/OBKoro1'}, {text: 'algorithm warehouse, link:' https://github.com/OBKoro1/Brush_algorithm '}]]}}}Copy the code

Sidebar configuration:

The configuration of the sidebar is relatively troublesome, I have done a detailed note inside, look carefully, you will know how to make their own tinkering.

Module. exports = {themeConfig: {sidebar:{// docs /accumulate = '/accumulate/': ['/accumulate/', // accumulate folder README. Md not drop down {title: 'accumulate ', children: ['/accumulate/JS/test', 'accumulate ',' accumulate ', 'accumulate ',' accumulate ', 'accumulate' Docs >accumulate>JS>test.md // add the first h1/h2/h3 header [}] to each suboption. '/ /algorithm/': ['/algorithm/', {title: '1', children: [ '/algorithm/simple/test' ] } ] } } }Copy the code

Other:

Code block compilation error:

Code like this will cause a compilation error, and VuePress will look for the variable in it and compile it as text:

{{}}, {{}}Copy the code

So our code block should be written in this form:

//```js{{}}, {{}}// The comment needs to be opened so that Vuepress will treat it as a code block instead of js
/ / ` ` `
Copy the code

This will also highlight our code (the first one is not highlighted, the second one is highlighted), making it a better reading experience:

Custom container to understand:

Change title:

::: tip replace the title of tip here is the content. : : :Copy the code

It’s actually in the documentation, but I’m just mentioning it here.

Support Emoji

The document only mentions Emoji support, so I found a list of them on GitHub and shared it.

A command line is posted to Github:

indocs/.vuepress/config.jsSet the correct base in:

If you want to publish to https://

.github. IO /, you can skip this step because base defaults to “/”.

If you want to publish to https://

.github. IO /

/ (that is, your repository is at https://github.com/

/

), set the base to “/

/”.

Module. exports = {base: '/test/', // if your repository is test}Copy the code

Create a step file:

In the root directory of project, create a deploy.sh file:

#! /usr/bin/env sh # Make sure scripts throw errors encountered set -e # Generate static file NPM run docs:build # Go to generated folder CD docs/.vuepress/dist # if it is published to custom domain name # echo 'www.example.com' > CNAME git init git add -a git commit -m 'deploy' # If published to https://<USERNAME>.github # git push -f [email protected]:<USERNAME>/<USERNAME>.github. IO. REPO=github project # git push -f [email protected]:<USERNAME>/<REPO>Copy the code

Set package. Json:

{
  "scripts": {
    "d": "bash deploy.sh"
  }
}
Copy the code

Deployment:

You can then push the latest changes to Github each time by running the following command line:

    npm run d
Copy the code

If you get tired of running and building projects on the command line, you can do something like this:

"Scripts ": {"dev": "vuepress dev docs", // NPM run dev" build": Nom run build "d": "bash deploy.sh" // Deploy project NPM run d},Copy the code

More:

In fact, there are many VuePress configuration and usage, such as the configuration of PWA, and the use of Vue components in Markdown, these functions I am still learning, so you must read the documentation!

conclusion

It’s as detailed as it can be, all the potholes I’ve encountered. Build up is really very simple, the heart is not as good as the action, readily spend an hour or two to build a loss, why not?

I hope that after watching the friends can click like/follow, your support is the biggest encouragement to me.

Blog, front end accumulate document, public account, GitHub

The above 2018.9.9