介紹
VuePress V2 是一個以 Markdown 為中心的靜態(tài)網(wǎng)站生成器熟吏。你可以使用 Markdown在新窗口打開 來書寫內容（如文檔胆描、博客等）互例，然后 VuePress 會幫助你生成一個靜態(tài)網(wǎng)站來展示它們。
VuePress 誕生的初衷是為了支持 Vue.js 及其子項目的文檔需求文兢，但是現(xiàn)在它已經(jīng)在幫助大量用戶構建他們的文檔、博客和其他靜態(tài)網(wǎng)站。
它是如何工作的淌喻？
一個 VuePress 站點本質上是一個由 Vue在新窗口打開 和 Vue Router在新窗口打開 驅動的單頁面應用 (SPA)。
路由會根據(jù)你的 Markdown 文件的相對路徑來自動生成雀摘。每個 Markdown 文件都通過 markdown-it在新窗口打開 編譯為 HTML 裸删，然后將其作為 Vue 組件的模板。因此阵赠，你可以在 Markdown 文件中直接使用 Vue 語法涯塔，便于你嵌入一些動態(tài)內容。
在開發(fā)過程中清蚀，我們啟動一個常規(guī)的開發(fā)服務器 (dev-server) 匕荸，并將 VuePress 站點作為一個常規(guī)的 SPA。如果你以前使用過 Vue 的話轧铁，你在使用時會感受到非常熟悉的開發(fā)體驗每聪。
在構建過程中，我們會為 VuePress 站點創(chuàng)建一個服務端渲染 (SSR) 的版本齿风，然后通過虛擬訪問每一條路徑來渲染對應的 HTML 药薯。
快速上手
依賴環(huán)境
創(chuàng)建并進入一個新目錄
mkdir vuepress-starter
cd vuepress-starter
初始化項目
- YARN
- NPM
git init
yarn init
將 VuePress 安裝為本地依賴
- YARN
- NPM
yarn add -D vuepress@next
在 package.json 中添加一些 scripts在新窗口打開
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
將默認的臨時目錄和緩存目錄添加到 .gitignore 文件中
echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore
創(chuàng)建你的第一篇文檔
mkdir docs
echo '# Hello VuePress' > docs/README.md
在本地啟動服務器來開發(fā)你的文檔網(wǎng)站
- YARN
- NPM
yarn docs:dev
VuePress 會在 http://localhost:8080在新窗口打開 啟動一個熱重載的開發(fā)服務器。當你修改你的 Markdown 文件時救斑，瀏覽器中的內容也會自動更新童本。
頁面
假設這是你的 Markdown 文件所處的目錄結構：
└─ docs
├─ guide
│ ├─ getting-started.md
│ └─ README.md
├─ contributing.md
└─ README.md
將 docs 目錄作為你的 sourceDir ，例如你在運行 vuepress dev docs 命令脸候。此時穷娱，你的 Markdown 文件對應的路由路徑為：
| 相對路徑 | 路由路徑 |
|---|---|
/README.md |
/ |
/contributing.md |
/contributing.html |
/guide/README.md |
/guide/ |
/guide/page.md |
/guide/page.html |
markdown 拓展語法
鏈接
在你使用 Markdown 的 鏈接語法在新窗口打開 時绑蔫， VuePress 會為你進行一些轉換。
Emoji ??
你可以在你的 Markdown 內容中輸入 :EMOJICODE: 來添加 Emoji 表情泵额。
前往 emoji-cheat-sheet在新窗口打開 來查看所有可用的 Emoji 表情和對應代碼配深。
輸入
VuePress 2 已經(jīng)發(fā)布 :tada: ！
輸出
VuePress 2 已經(jīng)發(fā)布 ?? 嫁盲！
目錄
如果你想要把當前頁面的目錄添加到 Markdown 內容中篓叶，你可以使用 [[toc]] 語法。
代碼塊
下列代碼塊擴展是在 Node 端進行 Markdown 解析的時候實現(xiàn)的羞秤。這意味著代碼塊并不會在客戶端被處理缸托。
行高亮
你可以在代碼塊添加行數(shù)范圍標記，來為對應代碼行進行高亮：
輸入
```ts{1,6-8}
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: '你好瘾蛋， VuePress',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
行數(shù)范圍標記的例子：
- 行數(shù)范圍：
{5-8} - 多個單行：
{4,7,9} - 組合：
{4,7-13,16,23-27,40}
行號
你肯定已經(jīng)注意到在代碼塊的最左側會展示行號俐镐。這個功能是默認啟用的，你可以通過配置來禁用它哺哼。
你可以在代碼塊添加 :line-numbers / :no-line-numbers 標記來覆蓋配置項中的設置佩抹。
站點配置
base
類型： string
默認值： /
詳情：部署站點的基礎路徑。
如果你想讓你的網(wǎng)站部署到一個子路徑下幸斥，你將需要設置它匹摇。它的值應當總是以斜杠開始，并以斜杠結束甲葬。舉例來說廊勃，如果你想將你的網(wǎng)站部署到 https://foo.github.io/bar/，那么 base 應該被設置成 "/bar/"经窖。
base 將會作為前綴自動地插入到所有以 / 開始的其他選項的鏈接中坡垫，所以你只需要指定一次。
主題配置
頂部導航欄設置
navbar
- 類型： false | (NavbarItem | NavbarGroup | string)[]
- 默認值： []
- 詳情：
導航欄配置画侣。
設置為 false 可以禁用導航欄冰悠。
為了配置導航欄元素，你可以將其設置為 導航欄數(shù)組 配乱，其中的每個元素是 NavbarItem 對象溉卓、 NavbarGroup 對象、或者字符串：- NavbarItem 對象應該有一個 text 字段和一個 link 字段搬泥，還有一個可選的 activeMatch 字段桑寨。
- NavbarGroup 對象應該有一個 text 字段和一個 children 字段。 children 字段同樣是一個 導航欄數(shù)組 忿檩。
- 字符串應為目標頁面文件的路徑尉尾。它將會被轉換為 NavbarItem 對象，將頁面標題作為 text 燥透，將頁面路由路徑作為 link 沙咏。
示例 1：
module.exports = {
themeConfig: {
navbar: [
// NavbarItem
{
text: 'Foo',
link: '/foo/',
},
// NavbarGroup
{
text: 'Group',
children: ['/group/foo.md', '/group/bar.md'],
},
// 字符串 - 頁面文件路徑
'/bar/README.md',
],
},
}
示例 2：
module.exports = {
themeConfig: {
navbar: [
// 嵌套 Group - 最大深度為 2
{
text: 'Group',
children: [
{
text: 'SubGroup',
children: ['/group/sub/foo.md', '/group/sub/bar.md'],
},
],
},
// 控制元素何時被激活
{
text: 'Group 2',
children: [
{
text: 'Always active',
link: '/',
// 該元素將一直處于激活狀態(tài)
activeMatch: '/',
},
{
text: 'Active on /foo/',
link: '/not-foo/',
// 該元素在當前路由路徑是 /foo/ 開頭時激活
// 支持正則表達式
activeMatch: '^/foo/',
},
],
},
],
},
}
最終配置效果
VuePress 站點必要的配置文件是 .vuepress/config.js辨图，它應該導出一個 JavaScript 對象。如果你使用 TypeScript 肢藐，你可以將其替換為 .vuepress/config.ts 故河，以便讓 VuePress 配置得到更好的類型提示。
config.ts 配置
import { defineUserConfig } from 'vuepress'
import type { DefaultThemeOptions } from 'vuepress'
export default defineUserConfig<DefaultThemeOptions>({
// 站點配置
base: '/vuepress/',
lang: 'zh-CN',
title: '你好 VuePress',
description: 'Just playing around',
// 主題和它的配置
theme: '@vuepress/theme-default',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
navbar: [
{
text: '指南',
link: ' https://v2.vuepress.vuejs.org/zh/guide/#%E5%AE%83%E6%98%AF%E5%A6%82%E4%BD%95%E5%B7%A5%E4%BD%9C%E7%9A%84',
},
// 嵌套 Group - 最大深度為 2
{
text: '參考',
children: [
{
text: 'VuePress',
children: [{text: '命令行接口',link: '/cli', activeMatch: '/cli',}, {text: '配置',link: '/config',activeMatch: '/config'}],
}
],
},
{
text: 'Github',
link: 'https://github.com/vuepress/vuepress-next',
},
],
},
})
VuePress Demo 代碼地址
https://gitee.com/kaiLee/Demo-VuePress
總結
優(yōu)點：配套工具較為完善吆豹，默認給的主題已經(jīng)集成度很高了忧勿，自定義選項多，更適合程序員發(fā)的文檔瞻讽。
缺點：V2 的文檔寫的有點糙，很多時候不知道怎樣配置啟用所需的功能熏挎。
一些記錄：
-
package.json中添加一些 scripts在新窗口打開速勇，分別用于調試yarn docs:dev和部署yarn docs:build。
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
- vuepress 更加適合開發(fā)者坎拐，包含各種字段配置烦磁。可搭配使用自定義的 vue 組件哼勇。反而提供給普通用戶的文檔寫的比較簡單都伪。
- Markdown 源文件放置在你項目的 docs 目錄，很多時候你需要在其中創(chuàng)建一個 .vuepress 目錄并進行配置积担。
- 使用的是默認的構建輸出目錄 (.vuepress/dist) 陨晶；
- 注意構建產(chǎn)物的路徑問題，需要設置正確的 base 選項帝璧。無論你是單獨部署到 nginx 還是 GitHub Pages先誉、Gitlab Pages 上。否則可能會樣式文件找不到導致網(wǎng)頁加載不正常的烁。
- yarn docs:dev 只是便于調試褐耳，例如我試了站點配置我修改了 lang 和 description 字段，但是只有構建產(chǎn)物后這兩個家伙才生效渴庆。
參考
首頁 | VuePress
https://v2.vuepress.vuejs.org/zh/
