- Introduction
- characteristic
- Environment construction
- In-depth development
- Template theme settings
- Other plugins
- A complete source code
Introduction
VuePress is a project for building blogs and simple websites. It is a static project based on vuejs and hosted by You Yuxi personally.
Based on such a system, it can be conveniently used for publishing small articles, such as help centers and official blogs, and supports parsing md files.
VuePress consists of two parts: one is a minimalist static website generator that supports theme development with Vue, and the other is a default theme optimized for writing technical documents. Its original intention was to support the documentation needs of Vue and its subprojects.
Its Markdown-centric project structure helps you focus on writing with minimal configuration; enjoy the development experience of Vue + webpack, you can use Vue components in Markdown, and you can use Vue to develop custom themes; it will be for each Page pre-rendering generates static HTML, and at the same time, when each page is loaded, it will run as a SPA.
VuePress official website: [ https://vuepress.vuejs.org/zh/ ]
characteristic
- Built-in Markdown extension optimized for technical documentation
- Ability to use Vue components in Markdown files
- Vue-driven custom theme system
- Automatically generate Service Worker
- Google Analytics integration
- Git-based "last update time"
- Multilingual support
- Free theme and plugin settings
The default theme contains
- Responsive layout
- Optional homepage
- Concise title search out of the box
- Algolia search
- Customizable navigation bar and sidebar
- Automatically generated GitHub links and page editing links
The above is the content provided by the official website; let's take a look at how to quickly create a technical document under practice. Of course, after you are familiar with its operation *, it is also a good choice to optimize and become your own blog! In line with the principle that the products produced by Youda must be fine products, I believe that the future development of VuePress will be very good!
* The purpose of this tutorial is to quickly build a basic model of technical documentation. For more specific configuration and instructions, please refer to the official website configuration
* https://vuepress.vuejs.org/zh/config/
https://vuepress.vuejs.org/zh/default-theme-config/
Environment construction
View nodejs version
Note: Node.js version> = 8
node -v
Global installation
npm install -g vuepress
Create project directory
mkdir vuepress-demo
cd vuepress-demo
Initialize the project, build and edit package.json
npm init -y
Enter package.json and modify the script content
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
Create a basic directory
vuepress-demo
├─package.json
├─docs
| ├─README.md
| ├─.vuepress
| | ├─config.js
| | ├─public
| | | └favicon.ico
Modify the configuration file-config.js
module.exports = {
title: 'Hello VuePress',
description: 'Hello, my friend!',
head: [
['link', {
rel: 'icon',
href: `/favicon.ico`
}]
],
dest: './docs/.vuepress/dist',
ga: '',
evergreen: true,
}
Modify README.md
VuePress provides out-of-the- box support for YAML front matter , we can imitate the vuepress homepage to optimize as follows:
---
home: true
heroImage: /favicon.ico
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 xxxxxx
---
Run the project
vuepress dev docs
Run the above code, and finally will prompt the preview URL http: // localhost: 8080 / (the port number can be modified according to the configuration https://vuepress.vuejs.org/zh/config/#port )
Open the URL, we can see To the following screen:
The content in README.md has been perfectly presented!
In-depth development
Configuration navigation
First create a file in the docs directory
The README.md under each folder is the content of the current directory;
let us configure the corresponding navigation through the config.js file
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{
text: 'Languages',
items: [
{ text: 'Chinese', link: '/language/chinese' },
{ text: 'English', link: '/language/english' }
]
},
{ text: 'External', link: 'https://www.baidu.com' },
]
}
Add content for README.md under the guide file:
## This is guide
content...
### title3
content...
### title3-01
## small title
content...
At this point, we use the full command to run the project:
# 开发调试状态
npm run docs:dev
# 项目发布
npm run docs:build
Run the project and click Navigation Guide, or click "Quick Start" from the Home page to see the following screen:
At this point we can see that the guide content has been successfully displayed, click on Lanuages to see the drop-down, and click External to jump to Baidu.
Configure the sidebar
Still add it under the themeConfig attribute under the config.js file:
sidebarDepth: 2,
sidebar: [
{
title: 'Guide',
collapsable: false,
children: ['/guide/']
}
]
Note: Use themeConfig.sidebarDepth to modify its behavior. The default depth is 1, which will extract the heading to h2. Setting it to 0 will disable the header links. At the same time, the maximum depth is 2, it will extract both h2 and h3 headings.
After configuration, run the project
to sum up
Through the above operations, this project has successfully completed the basic model of technical documents, such as more personalized configuration can be optimized according to demand through the official website.
Template theme settings
VuePress supports free theme definition, and provides a series of theme plugins on the official website, related URL:
https://github.com/vuepressjs/awesome-vuepress
Other plugins
# 自动边栏插件
vuepress-plugin-auto-sidebar
Comment plugin:
https://valine.js.org/quickstart.html
Excellent case:
www.z01.com/cli
http://wp.z01.com
https://vuepress-theme-reco.recoluan.com/
A complete source code
https://github.com/zoomla/waipo
[End of full text]