在以前爲了搭建 VuePress 的文檔,順帶製做了視頻教程,現在準備再次搭建一個 VuePress 的項目,一看本身的視頻居然有五個小時,天吶,我只是須要過一遍而已,因此從新整理成文檔吧,萬一未來又要用呢……javascript
固然,若是您以爲文字版不夠直觀,能夠前往觀看視頻版: 【☛ 視頻地址 ☚】 ,當時錄製完本地測試後以爲聲音大小還能夠,結果一套錄完了才發現聲音很小,因此推薦帶上耳機。css
VuePress 文檔示例html
對於環境準備不怎麼熟悉的仍是推薦看 視頻第一節 吧。vue
安裝 cmderjava
解壓完成後複製其路徑地址,將其添加到環境變量。node
使用 Win + R
鍵快速啓動 cmder
,若成功則添加環境變量成功。webpack
安裝 gitnginx
安裝包一路 next
便可,在桌面上右鍵出現 git bash here
或命令行中輸入 git --version
可以獲得具體的版本信息則安裝成功。git
安裝 nodejses6
安裝包一樣一路 next
便可,在命令行輸入 node -v
,若獲得具體版本信息則安裝成功。
安裝 yarn
安裝完成後,在命令行輸入 yarn --version
, 若獲得具體版本信息則安裝成功。
建立項目
建立項目能夠分爲兩種形式:
遠程倉庫
# xxx 爲你的遠程倉庫鏈接
git clone xxx
cd your_project_name
npm init -y
複製代碼
本地倉庫
# xxx 爲你的遠程倉庫鏈接
npm init your_project_name -y
cd your_project_name
git remote add origin xxx
複製代碼
安裝 vuepress
# 全局安裝
yarn global add vuepress@next # 或者:npm install -g vuepress@next
# 本地安裝
yarn add -D vuepress@next # 或者:npm install -D vuepress@next
複製代碼
配置 package.json
腳本
若是你的文檔不是在 docs
下,能夠按照你的設置來:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
複製代碼
上面配置完後,能夠進行測試:
yarn docs:dev # 或者:npm run docs:dev
複製代碼
若能在瀏覽器中正常訪問,則表示安裝成功。
Linux 配置與 Windows 所需一致,相信都用上 Linux 了,這點問題可以解決。
關於文件是如何渲染爲對應的路由的:
文件的相對路徑 | 頁面路由地址 |
---|---|
/README.md |
/ |
/guide/README.md |
/guide/ |
/config.md |
/config.html |
瞭解了這個基本的概念後,就能夠去配置對應的導航了。具體的導航欄配置介紹能夠看 官方文檔懂(www.bilibili.com/video/av433…) 。
在實踐後發現,若將全部內容放置在 docs/.vuepress/config.js
下將會很臃腫,難以閱讀與維護,推薦將其分離開,在根目錄下新建一個 config
文件夾:
// docs/.vuepress/config.js
const navConf = require('../../config/navConf.js');
module.exports = {
themeConfig: {
nav: navConf
},
}
複製代碼
舉個例子:
// config/navConf.js
module.exports = [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: '基礎', items: [
{ text: 'Algorithm', link: '/base/algorithm/' },
{ text: 'Interview', link: '/base/interview/' },
{ text: 'Clean', link: '/base/clean/' },
{ text: 'Git', link: '/base/git/' },
]},
{
text: '開發',
items: [
{ text: 'FrontEnd', items: [
{ text: 'JavaScript', link: '/FrontEnd/javascript/' },
{ text: 'CSS', link: '/FrontEnd/css/' },
{ text: 'Webpack', link: '/FrontEnd/webpack/' },
{ text: 'Nodejs', link: '/FrontEnd/nodejs/' },
]},
{ text: 'BackEnd', items: [
{ text: 'Koa', link: '/BackEnd/koa/' },
{ text: 'MongoDB', link: '/BackEnd/mongodb/' },
{ text: 'Nginx', link: '/BackEnd/nginx/' },
] },
]
}
];
複製代碼
側邊欄比導航欄要更爲繁瑣一些。具體的導航欄配置介紹能夠看 官方文檔,對應的 視頻 。
首先在 docs
文件夾下新建你須要的目錄及文件:
OS
├── centos
│ ├── 01-add-user.md
│ ├── 02-login-with-rsa-key.md
│ ├── 03-upload-file-to-server.md
│ └── README.md
├── manjaro
│ ├── 01-solve-problems-with-manjaro.md
│ └── README.md
└── windows
└── README.md
複製代碼
配置 config
文件,當文章不少的狀況下,還集中在 config
文件中,那就得炸了:
// docs/.vuepress/config.js
const sidebarConf = require('../../config/sidebarConf/index.js');
module.exports = {
themeConfig: {
sidebar: sidebarConf
},
}
複製代碼
文章須要進行分類,因此會分紅更多的子文件,經過 index.js
進行管理:
# config/sidebarConf
sidebarConf
├── Base
│ ├── algorithm
│ │ └── index.js
│ ├── clean
│ │ └── index.js
│ ├── git
│ │ └── index.js
│ └── interview
│ └── index.js
├── Guide
│ └── index.js
├── index.js
└── OS
├── centos
│ └── index.js
├── manjaro
│ └── index.js
└── windows
└── index.js
複製代碼
// config/sidebarConf/index.js
// 介紹
const guide = require('./Guide/index.js');
// 基礎
const git = require('./Base/git/index.js');
const interview = require('./Base/interview/index.js');
const algorithm = require('./Base/algorithm/index.js');
const clean = require('./Base/clean/index.js');
// 操做系統
const windows = require('./OS/windows/index.js');
const manjaro = require('./OS/manjaro/index.js');
const centos = require('./OS/centos/index.js');
/** * 側邊欄的配置 * 當路由深度越深時應當排序在更前方 * 示例: /frontend 和 /frontend/css * * 應當將 /frontend/css 寫在更上方 */
module.exports = {
// 指南 Guide
'/guide/': guide,
// 基礎 Base
'/Base/git/': git,
'/Base/interview/': interview,
'/Base/clean/': clean,
'/Base/algorithm/': algorithm,
// 操做系統 OS
'/OS/manjaro/': manjaro,
'/OS/windows/': windows,
'/OS/centos/': centos,
// 根目錄下的 sidebar, 對於全部未匹配到的都會應用該 sidebar
// '/': [''] // 此處選擇禁用
};
複製代碼
以 CentOS 舉個例子:
// config/sidebarConf/OS/centos/index.js
const utils = require('../../../../utils/index.js');
const children = ['','01-add-user','02-login-with-rsa-key','03-upload-file-to-server'];
module.exports = [
utils.genSidebar('CentOS', children, false),
];
複製代碼
genSidebar
函數:
const utils = {
genSidebar: function (title, children = [''], collapsable = true, sidebarDepth = 1) {
return {
title,
collapsable,
sidebarDepth,
children
}
}
};
module.exports = utils;
複製代碼
基本配置能夠幫助咱們作好網站的 SEO,更容易被搜索到。具體的基本配置介紹能夠看 官方文檔,對應的 視頻 。
// docs/.vuepress/config.js
module.exports = {
title: '飛躍高山與大洋的魚',
description: '飛躍高山與大洋的魚的文檔, vuepress 文檔',
}
複製代碼
更新時間,若是按照文檔進行配置的話時間格式是非中文的風格,解決很簡單:
// 添加多語言,改成國內便可
module.exports = {
locales: {
'/': {
lang: 'zh-CN',
}
},
themeConfig: {
lastUpdated: '上次更新',
},
}
複製代碼
全部的靜態資源都須要放置在 .vuepress/public
目錄下,你也能夠爲它們創建分類文件夾(這裏很差的效果是在預覽本地的 Markdown 文件時沒法看到圖片):
public
├── apple-touch-icon.png
├── app.png
├── base
│ └── interview
│ └── 1468042984788341.png
├── favicon-32x32.png
├── favicon.ico
├── FrontEnd
│ └── javascript
│ ├── es6_20190112123602.png
│ └── es6_20190112124206.png
├── manifest.json
複製代碼
以前作視頻的時候尚未
Travis CI
的使用說明,剛剛看的時候發現有了,昨天花了很久來硬啃Travis
官網,血虧……
這邊我發佈到的是 docs.shanyuhai.top
,因此 base
屬性默認爲空便可;如果發佈到 docs.shanyuhai.top/docs
則 base
屬性爲 docs
。
deploy.sh
文件示例:
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯誤
set -e
# 生成靜態文件
npm run docs:build
# 進入生成的文件夾
cd docs/.vuepress/dist
# 若是是發佈到自定義域名
echo 'docs.shanyuhai.top' > CNAME
git init
git add -A
git commit -m 'deploy'
# 若是發佈到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:shanyuhai123/documents.git master:gh-pages
cd -
複製代碼
參考文檔及視頻同上:
// docs/.vuepress/config.js
module.exports = {
themeConfig: {
// 你的 Git 項目地址,添加後會在導航欄的最後追加
repo: 'shanyuhai123/documents',
// 啓用編輯
editLinks: true,
// 編輯按鈕的 Text
editLinkText: '編輯文檔!',
// 編輯文檔的所在目錄
docsDir: 'docs',
// 假如文檔放在一個特定的分支下:
// docsBranch: 'master',
},
}
複製代碼
關於域名解析詳情能夠去看個人 視頻 (第五個視頻中的解析方式存在問題)。
解析方式須要改成 CNAME
的形式:
爲了方便閱讀,因此將內容進行了劃分: