如何采用VuePress構(gòu)建文檔網(wǎng)站

在建設(shè)博客的初期，我采用GitBook構(gòu)建了編碼專家的專欄系統(tǒng)。GitBook是基于Node.js的靜態(tài)頁構(gòu)建組件，可以將Markdown文檔渲染為靜態(tài)頁，支持插件擴展，使用非常簡單。由于它不支持深度的定制，使用了一段時間后，無法滿足我的要求了。有一天我看到某博客采用VuePress，簡潔美觀、功能強大。VuePress的幫助文檔非常詳實，是Vue團隊的誠意之作。正好我有一些Vue開發(fā)的功底，猶如出獄的色狼碰上了洗澡的劉亦菲。如果時間可以倒流，我絕對不會用WordPress來構(gòu)建我的博客。WordPress固然成熟，設(shè)計的太“重”了。

作者：傾城
博客： https://www.codingbrick.com
寄語：當(dāng)你意識到面子不重要時，你才算個真正的成年人。

在建設(shè)博客的初期，我采用GitBook構(gòu)建了編碼專家的專欄系統(tǒng)。GitBook是基于Node.js的靜態(tài)頁構(gòu)建組件，可以將Markdown文檔渲染為靜態(tài)頁，支持插件擴展，使用非常簡單。由于它不支持深度的定制，使用了一段時間后，無法滿足我的要求了。

有一天我看到某博客采用VuePress，簡潔美觀、功能強大。VuePress的幫助文檔非常詳實，是Vue團隊的誠意之作。正好我有一些Vue開發(fā)的功底，猶如出獄的色狼碰上了洗澡的劉亦菲。如果時間可以倒流，我絕對不會用WordPress來構(gòu)建我的博客。WordPress固然成熟，設(shè)計的太“重”了。

VuePress 是一個 Vue 驅(qū)動的靜態(tài)網(wǎng)站生成器，使用Markdown編寫文檔，提供成熟的主題、側(cè)邊欄、搜索功能等，輕松創(chuàng)建如何結(jié)構(gòu)清晰、易于導(dǎo)航和搜索的文檔網(wǎng)站。VuePress集成了自動化部署工具，可以將生成的靜態(tài)網(wǎng)站部署到各種托管平臺上，如GitHub Pages、Netlify等。VuePress還支持自動化的更新和發(fā)布，使得您可以輕松地更新網(wǎng)站內(nèi)容，并保持與代碼倉庫的同步。(來自VuePress官網(wǎng))

1 安裝Nodejs

根據(jù)Vuepress官網(wǎng)的部署指南，Vuepress v2.0依賴Node.js版本是v16.19.0+。推薦采用 yum 方式安裝首先確認鏡像地址是否可用，文件路徑是：/etc/yum.repos.d/CentOS-Base.repo，參考內(nèi)容如下所示：

# CentOS-Base.repo
#
# The mirror system uses the connecting IP address of the client and the
# update status of each mirror to pick mirrors that are updated to and
# geographically close to the client.  You should use this for CentOS updates
# unless you are manually picking other mirrors.
#
# If the mirrorlist= does not work for you, as a fall back you can try the 
# remarked out baseurl= line instead.
#
#
 
[base]
name=CentOS-$releasever - Base - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/os/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/os/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7
 
#released updates 
[updates]
name=CentOS-$releasever - Updates - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/updates/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/updates/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7
 
#additional packages that may be useful
[extras]
name=CentOS-$releasever - Extras - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/extras/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/extras/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/extras/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7
 
#additional packages that extend functionality of existing packages
[centosplus]
name=CentOS-$releasever - Plus - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/centosplus/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/centosplus/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/centosplus/$basearch/
gpgcheck=1
enabled=0
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7
 
#contrib - packages by Centos Users
[contrib]
name=CentOS-$releasever - Contrib - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/contrib/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/contrib/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/contrib/$basearch/
gpgcheck=1
enabled=0
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

yum 方式安裝的默認版本是16.18.1，達不到VuePress 2.0需要的最小版本16.19.0，必須指定版本號，命令如下：

# 檢查可用版本
yum list available nodejs
# 安裝指定版本
yum install nodejs-16.20.0

有時候 yum 源里面沒有相應(yīng)的Node.js版本，可以采用n模塊安裝指定版本，命令如下：

# 首先安裝npm模塊
yum install npm
# 利用npm安裝n模塊
npm install -g n
# 安裝最新版
n latest
# 或者指定版本
n 16.20.0
# 顯示版本號，證明安裝成功
node -v

2 初始化項目

VuePress的默認主題比較簡陋，缺乏SEO、Markdown 語法擴展等功能，推薦直接使用vuepress-theme-hope。這個版本提供了更加美觀的主題，默認集成許多實用的插件，大大增強了原有的功能。

首先初始化項目，命令如下：

npm init vuepress-theme-hope

這個命令會下載所有的依賴包，根據(jù)提示依次設(shè)置項目名稱、版本號等信息，最終會生成帶有空頁面的初始工程。

采用如下命令啟動調(diào)試：

npm run docs:dev

開發(fā)完畢后，可以構(gòu)建靜態(tài)頁部署到服務(wù)器上，靜態(tài)頁默認輸出路徑是 .vuepress/dist/，構(gòu)建命令如下：

npm run docs:build

3 遷移項目

如果重新部署項目，需要再次安裝依賴包，下載項目源碼后，在根目錄執(zhí)行命令：

npm install vuepress@next
npm install vuepress-theme-hope

4 開發(fā)經(jīng)驗

4.1 配置插件

VuePress支持很多插件，以安裝搜索插件為例，命令如下：

# 安裝搜索插件
npm i -D vuepress-plugin-search-pro

在 config.ts 文件里面找到 defineUserConfig，在配置項里增加代碼：

  plugins: [
    searchProPlugin({
      // 索引全部內(nèi)容
      indexContent: true,
      hotReload: true,
      // 為分類和標(biāo)簽添加索引
      customFields: [
        {
          getter: (page) => page.frontmatter.category,
          formatter: "分類：$content",
        },
        {
          getter: (page) => page.frontmatter.tag,
          formatter: "標(biāo)簽：$content",
        }
      ]
    })
  ]

4.2 百度統(tǒng)計

在 config.ts文件里面找到 defineUserConfig，在這個配置項的 header 里插入百度統(tǒng)計的腳本，如下所示：

  head: [
    // 百度統(tǒng)計
    [
      "script",
      {},
      `
      var _hmt = _hmt || [];
      (function() {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?去百度統(tǒng)計網(wǎng)站獲取相應(yīng)代碼";
        var s = document.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(hm, s);
      })();
        `
    ]
  ]

新建文件 enhanceApp.ts ，加入如下內(nèi)容：

export default ({ router }) => {
    /**
     * vuepress 是基于 vue 的單頁面應(yīng)用，頁面切換過程中不會重新加載頁面，不會觸發(fā)百度統(tǒng)計。
     * 以下代碼用于監(jiān)聽路由切換事件，當(dāng)切換頁面時,手動上報百度統(tǒng)計 
     */
    router.beforeEach((to, from, next) => {
      console.log("切換路由", to.fullPath, from.fullPath);
  
      //觸發(fā)百度的pv統(tǒng)計
      if (typeof _hmt != "undefined") {
        if (to.path) {
          _hmt.push(["_trackPageview", to.fullPath]);
          console.log("上報百度統(tǒng)計", to.fullPath);
        }
      }
      // continue
      next();
    });
  };

4.3 輔助腳本

懶得去記憶npm原始命令，編寫一個Shell腳本用來構(gòu)建站點，代碼如下：

#!/bin/sh

echo "please choose your option(1、2):"
echo "1: hot deploy for developing"
echo "2: build static page(default path: .vuepress/dist/)"

read item
if [ $item == 1 ]
then
  git pull
  npm run docs:dev
elif [ $item == 2 ]
then
  git pull
  npm run docs:build
else
    choose
fi

5 參考文檔

https://v2.vuepress.vuejs.org/zh/guide/
https://theme-hope.vuejs.press/zh/guide/

posted @ 2023-10-31 14:54 編碼專家閱讀(205) 評論(0) 收藏舉報

刷新頁面返回頂部