介紹
VuePress是一個用來構建博客以及簡易網站的項目，基於vuejs，由尤雨溪親自主持的一個靜態項目，靜態打包。
基於這樣的系統，可以方便用於小型文章發佈，如幫助中心、官方博客，支持解析md文件。
VuePress由兩部分組成：一部分是支持用 Vue 開發主題的極簡靜態網站生成器，另一個部分是爲書寫技術文檔而優化的默認主題。它的誕生初衷是爲了支持 Vue 及其子項目的文檔需求。
它以 Markdown 爲中心的項目結構，以最少的配置幫助你專注於寫作；享受 Vue + webpack 的開發體驗，可以在 Markdown 中使用 Vue 組件，又可以使用 Vue 來開發自定義主題；它會爲每個頁面預渲染生成靜態的 HTML，同時，每個頁面被加載的時候，將作爲 SPA 運行。
VuePress官網：[https://vuepress.vuejs.org/zh/]
特性
- 爲技術文檔而優化的內置 Markdown 拓展
- 在 Markdown 文件中使用 Vue 組件的能力
- Vue 驅動的自定義主題系統
- 自動生成 Service Worker
- Google Analytics 集成
- 基於 Git 的 “最後更新時間”
- 多語言支持
- 自由主題與插件設置
其中默認主題包含
- 響應式佈局
- 可選的主頁
- 簡潔的開箱即用的標題搜索
- Algolia 搜索
- 可自定義的導航欄 和 側邊欄
- 自動生成的 GitHub 鏈接和頁面的編輯鏈接
上述都是官網所提供的內容；下面讓我們來真正實踐下如何快速建立一個技術文檔，當然，你熟悉它的操作* 後，優化成爲自己的博客也是不錯的選擇！本着尤大出品必是精品的原則，相信VuePress未來發展會很不錯!
*本教程目的在於快速搭建技術文檔的基本模型，更具體的配置和說明請參考官網配置
*https://vuepress.vuejs.org/zh/config/
https://vuepress.vuejs.org/zh/default-theme-config/
環境搭建
查看nodejs版本
注意：Node.js 版本 >= 8
node -v
全局安裝
npm install -g vuepress
創建項目目錄
mkdir vuepress-demo |
|
cd vuepress-demo |
始化項目，建立並編輯 package.json
npm init -y
進入package.json，修改腳本內容
{ |
|
"scripts": { |
|
"docs:dev": "vuepress dev docs", |
|
"docs:build": "vuepress build docs" |
|
} |
|
} |
建立基本目錄
vuepress-demo |
|
├─package.json |
|
├─docs |
|
| ├─README.md |
|
| ├─.vuepress |
|
| | ├─config.js |
|
| | ├─public |
|
| | | └favicon.ico |
修改配置文件 - 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, |
|
} |
修改README.md
VuePress 提供了對 YAML front matter 開箱即用的支持，我們可以模仿vuepress首頁進行如下優化：
--- |
|
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 |
|
--- |
運行項目
vuepress dev docs
運行上述代碼，最後會提示預覽的網址http://localhost:8080/（端口號可根據配置進行修改https://vuepress.vuejs.org/zh/config/#port）
打開網址，我們就可以看到如下畫面：
README.md中的內容已完美呈現！
深度開發
配置導航
首先在docs目錄下建立文件
每個文件夾下的README.md就是當前目錄的內容；
讓我們通過config.js文件配置相應導航
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' }, |
|
] |
|
} |
爲guide文件下的README.md添加內容：
## This is guide |
|
content... |
|
### title3 |
|
content... |
|
### title3-01 |
|
## small title |
|
content... |
這時，我們使用完整的命令來運行項目：
# 開發調試狀態 |
|
npm run docs:dev |
|
# 項目發佈 |
|
npm run docs:build |
運行項目點擊導航Guide，或是通過Home頁點擊“快速上手”會看到如下畫面：
此時我們能夠看到guide內容已成功顯示，點擊Lanuages能看到下拉，點擊External會跳轉到百度.
配置側邊欄
依舊在config.js文件下的themeConfig屬性下添加：
sidebarDepth: 2, |
|
sidebar: [ |
|
{ |
|
title: 'Guide', |
|
collapsable: false, |
|
children: ['/guide/'] |
|
} |
|
] |
注：通過 themeConfig.sidebarDepth 來修改它的行爲。默認的深度是 1，它將提取到 h2 的標題，設置成 0 將會禁用標題（headers）鏈接，同時，最大的深度爲 2，它將同時提取 h2 和 h3 標題。
配置好後，運行項目
總結
通過上述操作，本項目已成功完成了技術文檔的基本模型，如更個性化的配置可通過官網按需求優化。
模板主題設置
VuePress支持自由主題定義，在官方網站提供了一系列的主題插件，相關網址：
https://github.com/vuepressjs/awesome-vuepress
其它插件
# 自動邊欄插件 |
|
vuepress-plugin-auto-sidebar |
評論插件：
https://valine.js.org/quickstart.html
優秀案例：
www.z01.com/cli
http://wp.z01.com
https://vuepress-theme-reco.recoluan.com/