如何用vuepress搭建網(wǎng)站

1.vuepress 介紹

類(lèi)似于大家所熟知的 hexo，vuepress 也可以用來(lái)生成靜態(tài)網(wǎng)頁(yè)。 vuepress 非常親切，想要做定制也非常容易，不像 hexo 定制那樣陌生。

根據(jù) vuepress 官網(wǎng)的介紹，VuePress 由兩部分組成：第一部分是一個(gè)極簡(jiǎn)靜態(tài)網(wǎng)站生成器，它包含由 Vue 驅(qū)動(dòng)的主題系統(tǒng)和插件 API，另一個(gè)部分是為書(shū)寫(xiě)技術(shù)文檔而優(yōu)化的默認(rèn)主題，它的誕生初衷是為了支持 Vue 及其子項(xiàng)目的文檔需求。

每一個(gè)由 VuePress 生成的頁(yè)面都帶有預(yù)渲染好的 HTML，也因此具有非常好的加載性能和搜索引擎優(yōu)化（SEO）。同時(shí)，一旦頁(yè)面被加載，Vue 將接管這些靜態(tài)內(nèi)容，并將其轉(zhuǎn)換成一個(gè)完整的單頁(yè)應(yīng)用（SPA），其他的頁(yè)面則會(huì)只在用戶瀏覽到的時(shí)候才按需加載。所以大家不用擔(dān)心自己網(wǎng)站無(wú)法被搜索引擎爬蟲(chóng)。

無(wú)論是 hexo 還是 vuepress，一個(gè)核心目的就是讓我們專注于內(nèi)容而不是網(wǎng)站建設(shè)，從這個(gè)角度來(lái)說(shuō)，其實(shí)兩個(gè)都不錯(cuò)，只不過(guò)對(duì)于有 vue 開(kāi)發(fā)經(jīng)驗(yàn)的小伙伴，vuepress 更加容易上手和定制。

相比于其他的電子書(shū)網(wǎng)站，vue 顯然更具備優(yōu)勢(shì)，例如：

Nuxt

VuePress 能做的事情，Nuxt 理論上確實(shí)能夠勝任，但 Nuxt 是為構(gòu)建應(yīng)用程序而生的，而 VuePress 則專注在以內(nèi)容為中心的靜態(tài)網(wǎng)站上，同時(shí)提供了一些為技術(shù)文檔定制的開(kāi)箱即用的特性。

Docsify / Docute

這兩個(gè)項(xiàng)目同樣都是基于 Vue，然而它們都是完全的運(yùn)行時(shí)驅(qū)動(dòng)，因此對(duì) SEO 不夠友好。如果你并不關(guān)注 SEO，同時(shí)也不想安裝大量依賴，它們?nèi)匀皇欠浅：玫倪x擇！

Hexo

Hexo 一直驅(qū)動(dòng)著 Vue 的文檔 —— 事實(shí)上，在把我們的主站從 Hexo 遷移到 VuePress 之前，我們可能還有很長(zhǎng)的路要走。Hexo 最大的問(wèn)題在于他的主題系統(tǒng)太過(guò)于靜態(tài)以及過(guò)度地依賴純字符串，而我們十分希望能夠好好地利用 Vue 來(lái)處理我們的布局和交互，同時(shí)，Hexo 的 Markdown 渲染的配置也不是最靈活的。

GitBook

我們的子項(xiàng)目文檔一直都在使用 GitBook。GitBook 最大的問(wèn)題在于當(dāng)文件很多時(shí)，每次編輯后的重新加載時(shí)間長(zhǎng)得令人無(wú)法忍受。它的默認(rèn)主題導(dǎo)航結(jié)構(gòu)也比較有限制性，并且，主題系統(tǒng)也不是 Vue 驅(qū)動(dòng)的。GitBook 背后的團(tuán)隊(duì)如今也更專注于將其打造為一個(gè)商業(yè)產(chǎn)品而不是開(kāi)源工具。

2.搭建

2.1 項(xiàng)目創(chuàng)建

具體的搭建其實(shí)很容易。

首先確保電腦本地安裝了 nodejs（如果本地的 vue 開(kāi)發(fā)環(huán)境齊全的話，就不用額外準(zhǔn)備了，如果對(duì) vue 不熟悉，不妨看看松哥的微人事視頻教程）。

環(huán)境準(zhǔn)備好之后，接下來(lái)開(kāi)始創(chuàng)建項(xiàng)目。

首先準(zhǔn)備一個(gè)新的目錄：

mkdir java-guide
cd java-guide

接下來(lái)對(duì)目錄進(jìn)行初始化：

npm init

初始化的過(guò)程中會(huì)有一些詢問(wèn)，需要配置就配置一下，不需要配置就直接回車(chē)，最終選擇 yes 即可。

 

接下來(lái)安裝 vuepress 依賴：

npm install -D vuepress

準(zhǔn)備好之后，接下來(lái)我們就可以創(chuàng)建第一篇文章了。

在一開(kāi)始創(chuàng)建的 java-guide 目錄下創(chuàng)建 docs 目錄（目錄名隨意），然后在目錄中創(chuàng)建一個(gè) README.md 文件，這個(gè)將是我們網(wǎng)站的首頁(yè)，README.md 中隨便寫(xiě)一行作為測(cè)試內(nèi)容。

 

接下來(lái)修改 package.json，添加兩行腳本：

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
},

docs:dev 是開(kāi)發(fā)環(huán)境下運(yùn)行，docs:build 則是項(xiàng)目編譯。

所有工作都準(zhǔn)備好之后，接下來(lái)就可以啟動(dòng)項(xiàng)目了，啟動(dòng)命令如下：

npm run docs:dev

 

項(xiàng)目啟動(dòng)成功后，瀏覽器地址欄輸入 http://localhost:8080/ 就可以看到啟動(dòng)效果。當(dāng)然現(xiàn)在的效果比較簡(jiǎn)單，就一個(gè) hello javaboy！

 

2.2 首頁(yè)配置

現(xiàn)在的頁(yè)面太簡(jiǎn)單了，我們可以對(duì)項(xiàng)目首頁(yè)進(jìn)行配置，打開(kāi) docs/README.md 文件，添加如下內(nèi)容：

---
home: true
heroImage: https://open.weixin.qq.com/qr/code?username=a_javaboy
heroText: 江南一點(diǎn)雨
tagline: Java 修煉手冊(cè)
actionText: 開(kāi)始學(xué)習(xí) →
actionLink: /springboot/
features:
- title: 純?cè)瓌?chuàng)
  details: 不做互聯(lián)網(wǎng)的搬運(yùn)工，松哥純手敲，純?cè)瓌?chuàng)教程。
- title: 成系列
  details: 成系列的教程合集，告別碎片化學(xué)習(xí)，Java 學(xué)習(xí)一步到位！
- title: 有案例
  details: 文章都有配套案例，部分系列有配套視頻，掃碼關(guān)注微信公眾號(hào)【江南一點(diǎn)雨】，及時(shí)獲取文檔更新通知！
footer: 關(guān)注微信公眾號(hào)【江南一點(diǎn)雨】，回復(fù) 888 ，領(lǐng)取 Spring Boot+Vue 項(xiàng)目實(shí)戰(zhàn)資料！

---

修改完成后，項(xiàng)目不用重啟，和 vue 一樣，會(huì)自動(dòng)熱更新，瀏覽器會(huì)自動(dòng)刷新，此時(shí)的首頁(yè)展示效果如下：

 

2.3 導(dǎo)航頁(yè)配置

導(dǎo)航頁(yè)的配置需要新建 docs/.vuepress/config.js 配置文件，文件內(nèi)容如下：

module.exports = {
    title: '江南一點(diǎn)雨',
    head: [
        ['link', {rel: 'icon', href: 'https://open.weixin.qq.com/qr/code?username=a_javaboy'}]
    ],
    themeConfig: {
        logo: 'https://open.weixin.qq.com/qr/code?username=a_javaboy',
        nav: [ 
            {text: '首頁(yè)', link: '/'},
            {text: '國(guó)際站', link: 'http://www.javaboy.org'},
            {text: '國(guó)內(nèi)站', link: 'http://www.itboyhub.com'}
        ],
        sidebar: 'auto'
    }
};

head 中配置的是瀏覽器的角標(biāo)，logo 則是瀏覽器導(dǎo)航欄的 logo。

配置完成后，顯示效果如下：

 

大家看到，上面多了導(dǎo)航欄。

在 themeConfig.nav 中配置導(dǎo)航欄，link 是導(dǎo)航欄鏈接的地址，可以將 link 替換成一個(gè) items ，items 是一個(gè)數(shù)組，items 會(huì)通過(guò)下拉框的形式展示出來(lái)，例如：

nav: [
    {text: '首頁(yè)', link: '/'},
    {text: '國(guó)際站', link: 'http://www.javaboy.org'},
    {text: '國(guó)內(nèi)站', link: 'http://www.itboyhub.com'},
    {text: '其他', items: [
        {text: '國(guó)際站', link: 'http://www.javaboy.org'},
        {text: '國(guó)內(nèi)站', link: 'http://www.itboyhub.com'}
    ]}
],

 

2.4 側(cè)邊欄配置

側(cè)邊欄的配置其實(shí)就是左邊菜單的配置。

使用 vuepress ，我們寫(xiě)文章可能會(huì)對(duì)文件進(jìn)行分類(lèi)，例如像下面這樣：

 

java 目錄放 Java 文章，python 目錄放 python 文章。我們隨便向目錄放幾篇文章進(jìn)來(lái)。

目錄結(jié)構(gòu)如下：

java-guide
├─package-lock.json
├─package.json
├─docs
|  ├─README.md
|  ├─python
|  |   ├─README.md
|  |   ├─python-1.md
|  |   └python-2.md
|  ├─java
|  |  ├─README.md
|  |  ├─java-1.md
|  |  └java-2.md
|  ├─.vuepress
|  |     └config.js

python 和 java 目錄下，對(duì)應(yīng)文章的訪問(wèn)路徑分別是：

• http://localhost:8080/java/java-1
• http://localhost:8080/java/java-2
• http://localhost:8080/python/python-1
• http://localhost:8080/python/python-2

注意，每篇文章頂部需要標(biāo)明文章的標(biāo)題（當(dāng)然也有其他方式配置文章標(biāo)題，松哥推薦這種方式），以 java-1.md 為例，文章頂部?jī)?nèi)容如下：

---
title: Java01
---

同時(shí)，java 和 python 目錄下都還有一個(gè) README.md 文件，這個(gè)文件的訪問(wèn)路徑是

• http://localhost:8080/java/

或者：

• http://localhost:8080/python/

這樣大家先把文件目錄的訪問(wèn)路徑搞清楚。

接下來(lái)，我們?cè)?docs/.vuepress/config.js 中配置側(cè)邊欄導(dǎo)航，如下：

sidebar: [
    {
        title: 'Java',
        path: '/java/',
        collapsable: false,
        sidebarDepth: 2,
        children: [
            '/java/java-1',
            '/java/java-2'
        ]
    },
    {
        title: 'Python',
        path: '/python/',
        collapsable: false,
        sidebarDepth: 2,
        children: [
            '/python/python-1',
            '/python/python-2'
        ]
    },
]

配置完成后，效果如下：

 

當(dāng)然，具體配置方式有很多種，松哥這里結(jié)合自己的使用方式先介紹一種，其他的配置方式小伙伴們可以參考官網(wǎng)。

3.部署

3.1 通用型

和 hexo 一樣，vuepress 最終也是編譯成靜態(tài)文件扔到服務(wù)器，所以如果你是自己的服務(wù)器，那么很簡(jiǎn)單，首先執(zhí)行如下命令進(jìn)行編譯：

npm run docs:build

 

編譯成功后會(huì)生成如下目錄結(jié)構(gòu)：

java-guide
├─docs
|  ├─.vuepress
|  |     ├─dist
|  |     |  ├─404.html
|  |     |  ├─index.html
|  |     |  ├─python
|  |     |  |   ├─index.html
|  |     |  |   ├─python-1.html
|  |     |  |   └python-2.html
|  |     |  ├─java
|  |     |  |  ├─index.html
|  |     |  |  ├─java-1.html
|  |     |  |  └java-2.html
|  |     |  ├─assets
|  |     |  |   ├─js
|  |     |  |   | ├─10.fd63f6ac.js
|  |     |  |   | ├─11.919333a2.js
|  |     |  |   | ├─2.5618c3b9.js
|  |     |  |   | ├─3.01385c65.js
|  |     |  |   | ├─4.7d5f245c.js
|  |     |  |   | ├─5.5e19538d.js
|  |     |  |   | ├─6.6523d9fe.js
|  |     |  |   | ├─7.6182cc1a.js
|  |     |  |   | ├─8.5aa56f7e.js
|  |     |  |   | ├─9.c492a2c2.js
|  |     |  |   | └app.803870cb.js
|  |     |  |   ├─img
|  |     |  |   |  └search.83621669.svg
|  |     |  |   ├─css
|  |     |  |   |  └0.styles.3f949b7f.css

dist 目錄下的文件就是我們要扔到服務(wù)器上的靜態(tài)文件，直接扔到 nginx 對(duì)應(yīng)的目錄下即可。

3.2 GitHub Pages

當(dāng)然，也可以利用 GitHub Pages 部署，省事！

GitHub Pages 我就不做過(guò)多介紹了，不了解的小伙伴可以參考這兩篇文章：

• 不用花一分線，松哥手把手教你上線個(gè)人博客
• 不花一分錢(qián)，把自己零散的知識(shí)整理成體系，制作成在線電子書(shū)

準(zhǔn)備好 GitHub 倉(cāng)庫(kù)之后，在項(xiàng)目根目錄下創(chuàng)建一個(gè)腳本文件 deploy.sh ，內(nèi)容如下：

#!/usr/bin/env sh

# 確保腳本拋出遇到的錯(cuò)誤
set -e

# 生成靜態(tài)文件
npm run docs:build

# 進(jìn)入生成的文件夾
cd docs/.vuepress/dist

# 如果是發(fā)布到自定義域名
echo 'docs.javaboy.org' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果發(fā)布到 https://<USERNAME>.github.io
git push -f git@github.com:onedocs/onedocs.github.io.git master

cd -

這個(gè)有兩個(gè)地方需要根據(jù)自己的實(shí)際情況修改，一個(gè)是如果需要自定義域名，改成自己的域名；另一個(gè)是 GitHub 賬戶，改成自己的。

最后，執(zhí)行該腳本即可。執(zhí)行完成后，項(xiàng)目就上線了。

如果是 Windows 系統(tǒng)，按照這個(gè)腳本中的命令自行執(zhí)行即可，都是比較簡(jiǎn)單的命令，就不再贅述。