Preface:

VuePress is a project written by THE University of Utah to support the documentation requirements of Vue and its subprojects. The interface is simple and easy to use, with the architecture of a project being put together in an hour. There are a lot of these types of documents out there, and if you have a project to write technical documentation, VuePress can definitely be one of your options.

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 generate Service workers
  • Google Analytics integration
  • Git-based “Last Updated Time”
  • Multilingual support
  • The default topics include:

It is recommended to read the official documentation first

Effect:

You might build a document that looks something 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 new folder, or use the following command to create a new folder:

mkdir project
Copy the code

Project initialization

Go to the project folder and use the command line to initialize the project YARN official document:

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

Tips: If YARN is not installed, an error message is displayed

Install YARN (if there are problems, go to CMD and start again)

npm install -g yarn
Copy the code

A package.json file will be created 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 under the root of project:

This document will be used as the root 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 placed here

in.vuepressCreate it under folderconfig.js:

touch config.js
Copy the code

Echo test> echo test

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

You can add the following configuration first:

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

in.vuepressCreate public folder under folder:

mkdir public
Copy the code

Vuepress /dist/ this folder is used to store static resources, which when packaged will be placed in the root directory of.vuepress/dist/.

Home page (like VuePress document home page)

Create a readme.md under the docs folder:

The default theme provides a home page. Just set home: True as shown below. Put the following Settings into readme. md and you will see the same home page as VuePress.

-- Home: true heroImage: /logo.jpg actionText: Get started → actionLink: /zh/ Guide/Features: - Title: Markdown-centric project structure helps you focus on writing with minimal configuration. - 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: MIT Licensed | Copyright © 2018 - present Evan You -Copy the code

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

Our project structure has been set up:

│ ├─ ├─ public │ ├─ customs.txt ├─ customs.txt ├─ customs.txtCopy the code

inpackage.jsonAdd two startup commands to:

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

Start your VuePress:

The default is port localhost:8080.

Or: NPM run docs:devCopy the code

Construction:

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

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

Basic configuration:

The most standard, of course, is the official documentation, which allows you to configure config.js for your own needs.

Take a look at my config.js configuration:

Module. exports = {title: 'url ', description:' url ', // head: [['link', {rel: 'icon', href: '/favicon.ico'}], // Add a custom favicon], base: '/web_accumulate/', // this is the appropriate configuration to deploy to Github. Markdown: {lineNumbers: true // block display 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' // git git date of each file}};Copy the code

Navigation bar configuration:

Module. exports = {themeConfig: {nav:[{text: 'front end ', link: '/algorithm/'}, // internal link:' docs ', link: 'http://obkoro1.com/'}, // external links // dropdown {text: 'GitHub', items: [{text: 'GitHub address ', 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, their own tinkering will know how to do.

Module. exports = {themeConfig: {sidebar:{// accumulate/' /accumulate/': module. Exports = {themeConfig: {sidebar:{// accumulate/': [' accumulate/', // accumulate/', children: [' accumulate/JS/test', // accumulate/JS/test] Docs > the accumulate > JS > test. The md / / automatic file. The title of each md option is the first of the md file h1 / h2, h3 title]}], '/algorithm/': ['/algorithm/', {title: '1', {title:' 1', children: [ '/algorithm/simple/test' ] } ] } } }Copy the code

Other:

Code block compilation error:

A code like this will cause a compilation error. VuePress will find the variable and compile it to text:

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

So our code block is written like this:

/ / ` ` ` js {{}} {{}} / / comment need to open this vuepress inside this package as a block of code instead of js / / ` ` `Copy the code

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

Custom containers:

Change the 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.

Support Emoji

The document only mentions supporting Emoji. I found the list of Emoji on GitHub and clicked the preview to share it.

A command line posted to Github:

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

If you want to post to https://

.github. IO /, you can skip this step, because base is “/” by default.

If you plan to post to https://

.github. IO /

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

/

), set base to “/

/”.




Module. exports = {base: '/ /test/', // exports = {base: '/ /test/'}Copy the code

Create step file:

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

#! /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 # git push -f [email protected]:<USERNAME>/<USERNAME>.github. IO. Git master -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’re bored with the command line for running and building projects, you can do as I did:

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

More:

In fact, VuePress has many configurations and uses, such as PWA configuration, and the use of Vue components in Markdown. I am still exploring these functions, so please check the documentation! VuePress demo: github.com/xugaoyi/vue…

Transfer: segmentfault.com/a/119000001… + Practice supplement