VuePress 是一款使用 Vue 驅動的靜態網站生成器,是 Vue 的作者 Evan You 爲了方便文檔的編寫而開發的。
- 默認主題與 Vue 官方文檔一致
- 簡潔,少配置,高性能
- Markdown 專爲技術文檔提供拓展
- 自帶 PWA
- 自定義主題,可定製程度完全由自己決定
官方文檔:由於 1.x 還處於測試階段,可能隨時變更,所以建議選用 0.x 版本
1. 初始化
安裝
首先需要安裝 vuepress
可以使用全局安裝:(選一個版本安裝即可,使用 yarn 或 npm 都可以)
yarn add global vuepress # 0.x 版本
yarn add global vuepress@next # 1.x 版本
也可以使用局部安裝,在你的項目根目錄下:
yarn add -D vuepress
yarn add -D vuepress@next
注意有一個坑,我遇到過,安裝 vuepress@next 以及其他插件時,默認會安裝 alpha 0 版本,需要修改 package.json 文件,更改版本號,再重新使用 yarn 安裝一下。
另外,全局安裝與局部安裝在後面的部署命令中會有些差別。
結構目錄
.
├── docs
│ ├── .vuepress
│ │ ├── public
│ │ └── config.js
│ │
│ └── README.md
│
└── package.json
可詳細查看:目錄結構
2. 配置 config.js 文件
基礎配置
module.exports = {
title: "destiny'Note",
description: "生命的意義不僅是活着,而是我們給別人的生命帶來了何種不同。",
base: '/', // 項目根路徑
dest: '/dist/', // 打包後的文件夾路徑,爲了方便,我把 dist 文件夾放到了根目錄上
// head 標籤中的額外內容
head: [
['link', { rel: 'icon', href: '/favicon.ico' }] // 這個是標籤頁 logo
],
// 語言配置
locales: {
// 鍵名是該語言所屬的子路徑
// 作爲特例,默認語言可以使用 '/' 作爲其路徑。
'/': {
lang: 'zh-CN', // 將會被設置爲 <html> 的 lang 屬性
}
}
}
可詳細查看:配置
主題配置
module.exports = {
...
// 主題配置
themeConfig: {
// 頂部導航
nav: [
{ text: '首頁', link: '/' },
{ text: '歸檔', link: '/archives/'},
{ text: '分類', link: '/categories/' },
{ text: '標籤', link: '/tags/' },
{ text: '關於我', link: '/about/' }
],
// 側邊欄
sidebar: [
'/'
],
sidebarDepth: 2, // 默認 1 提取到 h2,0 爲禁用,2 爲 h2,h3
displayAllHeaders: false, // 默認值:false 側邊欄只會顯示由當前活動頁面的標題組成的鏈接
activeHeaderLinks: true, // 默認值:true 滾動時通過 hash 高亮側邊欄標題
// Git 倉庫和編輯鏈接
repo: 'username/repo', // 你的倉庫
repoLabel: 'GitHub', // 導航欄上的文本
editLinks: true,
// 默認爲 "Edit this page"
editLinkText: '編輯此頁面'
}
}
可詳細查看:默認主題配置
3. 首頁
配置 docs 下的 README.md 文件即可:
---
home: true
heroImage: /hero.jpg
heroText: Hero
tagline: Hero 副標題
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 簡潔至上
details: 以 Markdown 爲中心的項目結構,以最少的配置幫助你專注於寫作。
- title: Vue驅動
details: 享受 Vue + webpack 的開發體驗,在 Markdown 中使用 Vue 組件,同時可以使用 Vue 來開發自定義主題。
- title: 高性能
details: VuePress 爲每個頁面預渲染生成靜態的 HTML,同時在頁面被加載的時候,將作爲 SPA 運行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---
首頁必須設置 home 爲 true。默認樣式與官方文檔首頁一致。
4. 開發和部署
定義腳本
初始化 package.json,如果是局部安裝的話,這個文件已經存在,不需要執行這個命令
yarn init
編輯 package.json 文件,添加如下腳本:(這裏需要注意)
{
...
// 全局安裝
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
}
// 局部安裝
"scripts": {
"dev": "npx vuepress dev docs",
"build": "npx vuepress build docs"
}
}
個人不喜歡官方的寫法,就把名稱寫的簡潔一些。
運行腳本命令:
yarn dev # 開發
yarn build # 打包
部署到 GitHub Pages 上
部署到 GitHub 上,首先要在 GitHub 上建立倉庫,這裏省略。
然後再本地初始化倉庫,並關聯遠程倉庫
git init
git remote add origin <repo> # 你的遠程倉庫
打包之後把整個項目上傳到 master 分支上,方便管理
git add -A
git commit -m 'init blog'
# 首次提交需要 --set-upstream,後續可以去掉
git push --set-upstream origin master # 所有代碼推送到遠程倉庫的 master 分支上
單獨將打包好的文件上傳到 gh-pages 分支上,自動會生成 GitHub Pages,在倉庫設置裏可以查看到相應地址。
git subtree push --prefix dist origin gh-pages # 只將 dist 上傳到 gh-pages 分支
注意,最好配置一個 .gitignore 文件,去掉不需要上傳的文件和文件夾。
自動化部署
每一次更新完文章之後,都需要敲一大串代碼,才能重新部署,顯得很繁瑣。那麼我們來讓這些命令合併成一個命令吧。
項目根目錄下創建 deploy.sh 文件:
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯誤
set -e
# 生成靜態文件
yarn build
# 提交到歷史區,$1 爲運行 sh 時的第一個參數
git add -A
git commit -m $1
# 提交到 master 分支
git push origin master
# 將 dist 文件提交到 gh-pages 分支
git subtree push --prefix dist origin gh-pages
# 退出命令
exit 0
然後在 package.json 文件中配置腳本:
{
"scripts": {
//...
"deploy": "bash deploy.sh"
}
}
後續部署直接使用命令:
yarn deploy "updatedBlog"
需要注意的是,後面帶的消息,不能使用空格隔開(本人對 shell 腳本不熟悉,查找了也沒明白,希望有大神指點一下),使用了空格,就會導致只提交了空格前的消息
另外,這個命令需要在 git bash 中使用,不能在 Windows 的命令行中使用。
5. 後續
太喜歡 VuePress 了,因爲後面都託管給 Vue 了,所以速度飛快。
後續會出一個如何修改默認主題的文章。