vuepress文档服务器,使用 vuepress 快速搭建文档
vuepress官方教程，em...也是用vuepress搭建的，哈哈。
這句很經(jīng)典，也是表明了vuepress最好的用處：
VuePress 專注在以內(nèi)容為中心的靜態(tài)網(wǎng)站上，同時提供了一些為技術(shù)文檔定制的開箱即用的特性。
使用這個框架，不需要服務(wù)器，不需要空間，只要有支持pages的git托管倉庫就可以搭建一個技術(shù)文檔站點，任性！當(dāng)然你也可以放到自己的服務(wù)器上直接作為靜態(tài)網(wǎng)站使用，無所謂。
我這里使用的是碼云Gitee，國內(nèi)的，好用！
在碼云上申請賬號，然后新建倉庫，這些流程不做演示了。我這里的倉庫名稱是vuepress，劃重點，后面要用！！！
image.png
因為后面所作的操作，都在這里面，后面還要用到這個倉庫
git到本地(從下圖指示找倉庫下載地址位置，按個人喜歡的方式把項目clone到本地)
git clone https://gitee.com/axhuangs/vuepress.git
image.png
image.png
進入到本地倉庫，并且安裝vuepress框架到本地(npm和yarn喜歡哪個都行，但是需要安裝相應(yīng)的工具)
下面開始按順序來做：
1. 使用你喜歡的包管理器進行初始化， 我比較喜歡npm
npm init
// yarn init
最后會有一句確認(rèn)信息截圖沒有截全Is this OK? (yes) 敲入yes或者y直接回車就可以
image.png
2.將 VuePress 安裝為本地依賴(就是下載vuepress框架到本地)
npm install -D vuepress
//yarn add -D vuepress
image.png
image.png
不要在意太多黃色的細節(jié)，正經(jīng)的應(yīng)該這樣就表明安裝成功了。
另外我一直再用vscode的窗口操作，所以項目完成之后，會出現(xiàn)下面的提示：
image.png
點擊是，主要是一般node_modules文件有的沒有的一大堆(有一部分這個原因，所以node的作者又生了個新兒子deno)，占空間比較大，所以一般情況下咱們不上傳到遠端，浪費空間，有package.json文件，在這個項目下載到別的地方的時候在根目錄運行npm install一下就可以了，你會驚奇的發(fā)現(xiàn)，node_modules又出來了。
3.重點來了！新建第一個文檔
老老實實創(chuàng)建一個文件夾docs， 然后新建一個文件README.md，并且用markdown的方式寫上一句，嗯，老老實實...， 我這里用官方提供的方式，報錯...
# Hello VuePress
4.在 package.json 中添加下面的話
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
很重要的兩句話，一句是運行本地開發(fā)環(huán)境，一句是打包準(zhǔn)備部署到線上的文件
5.在本地啟動服務(wù)器 來查看成果了
npm run docs:dev
//yarn docs:dev
經(jīng)過各種輸出和好看的進度條之后，你會看到下面的信息：
image.png
說明啟動起來了，瀏覽器打開: http://localhost:8080/:
image.png
那么現(xiàn)在你修改README.md文件， 這里會實時更新
image.png
到這里，前期搭建基本上及可以算是搞定了。
如果需要markdown的書寫方式的話，可以去看看
再墨跡點很重要的東西最后在說怎么布置到碼云上
現(xiàn)在頂部和左側(cè)還是跟官方文檔差點兒東西
左側(cè)導(dǎo)航配置
在docs文件夾下新建文件夾.vuepress 并且新建config.js
module.exports = {
title: 'vuepress文檔', // 文檔標(biāo)題，左上角顯示
description: 'vuepress文檔描述',
base: '/vuepress/', // 這里寫你的倉庫名稱
head: [
['link', { rel: 'shortcut icon', type: "image/x-icon", href: `/jyjwebdocs/favicon.ico` }]
], //這里配置你的網(wǎng)頁頭部信息等
themeConfig: {
/**
* 設(shè)置側(cè)邊欄最大深度
* 一般是以單個md文件中的 # ## ### #### 這幾個標(biāo)題文字為錨點自動生成導(dǎo)航
* **/
sidebarDepth: 4,
// 設(shè)置側(cè)邊欄內(nèi)容
sidebar: [
{
title: '第一個側(cè)邊欄',
collapsable: false, // 是否具有展開收起功能
children: ['/firstslde/'] // 這個是根據(jù)自己的需求來訂，對應(yīng)自己在docs下的文件夾名，默認(rèn)首頁是README.md
}
]
}
}
注意：每次配置config.js文件都需要重新運行一下項目
這是目前的目錄結(jié)構(gòu):
image.png
這是docs/firstside/README.md下的內(nèi)容:
# 第一個側(cè)邊欄
firstside
firstside
firstside
firstside
## 二級第一個側(cè)邊欄
二級第一個側(cè)邊欄
二級第一個側(cè)邊欄
## 二級第二個側(cè)邊欄
二級第二個側(cè)邊欄
二級第二個側(cè)邊欄
### 三級第一個側(cè)邊欄
三級第一個側(cè)邊欄
三級第一個側(cè)邊欄
三級第一個側(cè)邊欄
## 二級第三個側(cè)邊欄
二級第三個側(cè)邊欄
二級第三個側(cè)邊欄
二級第三個側(cè)邊欄
重新運行npm run docs:dev之后效果是這樣的:
image.png
當(dāng)然有的時候整篇內(nèi)容會比較長，或者分不同的模塊，那么就可以多建幾個md文件，并在config.js中配置一下
比如我在/firstside/文件夾下創(chuàng)建了otherModel.md文件，并創(chuàng)建了child文件夾，如下：
image.png
config.js的配置是這樣的：
// 設(shè)置側(cè)邊欄內(nèi)容
sidebar: [
{
title: '第一個側(cè)邊欄',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/']
}
// 根據(jù)自己的需求來訂，對應(yīng)自己在docs下的文件夾名，默認(rèn)首頁是README.md
]
運行效果是這樣的：
image.png
config.js中的sidebar的配置方式可以組合各種姿勢，下面只是一個小栗子，可以試下，當(dāng)然開啟更多組合，需要你來定，這里只是介紹一下基礎(chǔ)方式
這是目錄結(jié)構(gòu)：
image.png
這是config.js側(cè)邊欄設(shè)置
// 設(shè)置側(cè)邊欄內(nèi)容
sidebar: [
{
title: '第一個側(cè)邊欄',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/'] // 這個是根據(jù)自己的需求來訂，對應(yīng)自己在docs下的文件夾名，默認(rèn)首頁是README.md
},
{
title: '第二個側(cè)邊欄',
collapsable: true, // 開啟展開收起功能，注意下圖中菜單名稱旁邊的小角標(biāo)
children: [
'/second/',
{
title: '側(cè)邊欄組合',
collapsable: true,
children: [
'/second/child/',
'/second/child/secondChild'
]
}
]
}
]
最后的展示效果：
image.png
側(cè)邊欄差不多就這些了，當(dāng)然還有頂部導(dǎo)航部分設(shè)置
// 設(shè)置菜單
nav: [
{ text: '首頁', link: '/' },
{ text: '其他文檔', items: [
{ text: 'demo1', link: 'http://www.baidu.com' },
{ text: 'demo2', link: 'http://www.baidu.cn' },
] }
],
nav與sidebar為同級
效果：
image.png
config.js的全部內(nèi)容
module.exports = {
title: 'vuepress文檔',
description: 'vuepress文檔描述',
base: '/vuepress/', // 這里寫你的倉庫名稱
head: [
['link', { rel: 'shortcut icon', type: "image/x-icon", href: `/jyjwebdocs/favicon.ico` }]
], //這里配置你的網(wǎng)頁頭部信息等
themeConfig: {
nav: [
{ text: '首頁', link: '/' },
{ text: '其他文檔', items: [
{ text: 'demo1', link: 'http://www.baidu.com' },
{ text: 'demo2', link: 'http://www.baidu.cn' },
] }
],
/**
* 設(shè)置側(cè)邊欄最大深度
* 一般是以單個md文件中的 # ## ### #### 這幾個標(biāo)題文字為錨點自動生成導(dǎo)航
* **/
sidebarDepth: 4,
// 設(shè)置側(cè)邊欄內(nèi)容
sidebar: [
{
title: '第一個側(cè)邊欄',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/'] // 這個是根據(jù)自己的需求來訂，對應(yīng)自己在docs下的文件夾名，默認(rèn)首頁是README.md
},
{
title: '第二個側(cè)邊欄',
collapsable: true,
children: [
'/second/',
{
title: '側(cè)邊欄組合',
collapsable: true,
children: [
'/second/child/',
'/second/child/secondChild'
]
}
]
}
]
}
}
基本上頁面配置就這些，主要還是config.js的配置
如果想放入圖片的話
個人覺得最好的方式就是哪里需要放哪里，但是目前還沒想到怎么配置
目前總結(jié)到的方法是，把圖片放到新建目錄.vuepress/public/assets/下，
這樣打完包之后圖片會被load到dist/assets/下面
image.png
然后再使用的地方，基本可以用兩種方式引入
效果是這樣的
image.png
image.png
最最重要的點來了
打包:
npm run docs:build
image.png
打包完成，使用git把整個源碼上傳到碼云吧
然后來到碼云的倉庫嘍
image.png
找到你的倉庫，打開Gitee Pages
image.png
點擊啟動，等待部署完成
image.png
大工告成，上面已經(jīng)出現(xiàn)了你的文檔鏈接
注意：每次修改文檔內(nèi)容，哪怕一個標(biāo)點符號，都需要到這里更新一下，才能正確顯示文檔
總結(jié)
以上是生活随笔為你收集整理的vuepress文档服务器,使用 vuepress 快速搭建文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 文件共享服务器连接数问题,共享服务器上连
- 下一篇： 相对路径，绝对路径