VuePress-theme-hope2 搭建個(gè)人網(wǎng)站，保姆級(jí)教程，包含自動(dòng)部署、評(píng)論、搜索等功能
VuePress 是一個(gè)以 Markdown 為中心的靜態(tài)網(wǎng)站生成器。好處是可以使用 Markdown 來(lái)書(shū)寫(xiě)內(nèi)容文檔或者博客。
VuePress 誕生的初衷是為了支持 Vue.js 及其子項(xiàng)目的文檔需求。
在明確你的目標(biāo)之后，先不著急立馬搭建項(xiàng)目。
?? 你喜歡哪個(gè)主題
因?yàn)閂uePress除了默認(rèn)的主題外，提供了擴(kuò)展主題、擴(kuò)展插件的能力，不同的主題又組織了不同的插件集合來(lái)完成開(kāi)箱即用的功能。
所以，你首先應(yīng)該使用哪款主題作為你的個(gè)人完整風(fēng)格。
比較熱門(mén)你的主題有：
- vuepress默認(rèn)主題 21.7k?
- vuepress-theme-hope 1.4k?
- vuepress-theme-reco，（2.0還在測(cè)試階段） 1.6k?
- vuepress-theme-vdoing 3.5k?
不同主題的之間的最明顯的差異就是默認(rèn)的樣式不同，其次就是默認(rèn)提供的功能不同。
首先，我們看看各個(gè)主題默認(rèn)的樣式。
默認(rèn)主題案例
vue系列早先版本的官網(wǎng)大多數(shù)都是默認(rèn)主題。
圖片
vuepress-theme-hope案例
蟬沐風(fēng)的碼場(chǎng): https://www.chanmufeng.com/
vuepress-theme-reco 案例：
萌萌噠草頭將軍（我的舊博客）: https://mmdctjj.github.io/blogs/
圖片
vuepress-theme-reco 2.0案例：
異想之旅のBlog：https://www.yixiangzhilv.com/
圖片
vuepress-theme-vdoing 案例：
Dra-M: https://dra-m.com/
圖片
相信看到這里，應(yīng)該有自己心儀的主題了吧
我用的主題是：vuepress-theme-reco，主題和默認(rèn)主題相似
主要功能是新增了一些圖標(biāo)、新增了Tag、新增了時(shí)間軸等常用功能，
缺點(diǎn)是：功能還不夠豐富，圖標(biāo)比較少，無(wú)法有效添加摘要、閱讀時(shí)間、字?jǐn)?shù)統(tǒng)計(jì)等功能。
相反，vuepress-theme-hope 這些做的都不錯(cuò)，成為我新的選擇。
?? 搭建項(xiàng)目
?? 初始化項(xiàng)目
如果你選擇了一個(gè)主題，請(qǐng)務(wù)必使用該主題提供的腳手架工具創(chuàng)建項(xiàng)目。這樣可以減少很多配置上的麻煩。
npm init vuepress-theme-hope blogsNeed to install the following packages:
create-vuepress-theme-hope@2.0.0-beta.233
Ok to proceed? (y)Need to install the following packages:
create-vuepress-theme-hope@2.0.0-beta.233
Ok to proceed? (y) y
? Select a language to display / 選擇顯示語(yǔ)言
english (US)
? 簡(jiǎn)體中文
D:\work>npm init vuepress-theme-hope blogs2
Need to install the following packages:
create-vuepress-theme-hope@2.0.0-beta.233
Ok to proceed? (y) y
? Select a language to display / 選擇顯示語(yǔ)言 簡(jiǎn)體中文
? 選擇包管理器 yarn
生成 package.json...
? 設(shè)置應(yīng)用名稱(chēng) blogs2
? 設(shè)置應(yīng)用版本號(hào) 2.0.0
? 設(shè)置應(yīng)用描述 A project of vuepress-theme-hope
? 設(shè)置協(xié)議 MIT
? 項(xiàng)目需要用到多語(yǔ)言么? No
? 是否需要一個(gè)自動(dòng)部署文檔到 GitHub Pages 的工作流？ Yes
? 你想要?jiǎng)?chuàng)建什么類(lèi)型的項(xiàng)目？ blog
生成模板...
? 是否初始化 Git 倉(cāng)庫(kù)? Yes
? 選擇你想使用的源 當(dāng)前源初始化目錄結(jié)構(gòu)如下
圖片
?? 首頁(yè)配置
其中，src 目錄下的 README.md即為博客或者文檔的首頁(yè)。
等待下載完畢，執(zhí)行 npm run docs:dev
打開(kāi)頁(yè)面，可以看到博客的首頁(yè)如下：
圖片
可以通過(guò)設(shè)置heroFullScreen: false，關(guān)閉hero背景全屏。
下滑之后文章的列表如下：
圖片
文章的列表來(lái)自于項(xiàng)目中所有的markdown文件，你可以在每個(gè)md文件的frontmatter中設(shè)置文章的標(biāo)題、封面、分類(lèi)、標(biāo)簽、日期、是否在文章列表中顯示。
---
title: ????vue3自定義指令實(shí)踐
isTimeLine: true
date: 2023-07-03
category:
- 前端
tag:
- JavaScript
- Vue
---通過(guò)設(shè)置article 為 false將文章在列表中排除。
站點(diǎn)的基本信息、頂部的hero信息、項(xiàng)目鏈接、底部的footer信息都可以在README.md中配置。
我的配置如下：具體可以參考：https://theme-hope.vuejs.press/zh/config/frontmatter/blog-home.html
home: false
layout: BlogHome
icon: home
title: 首頁(yè)
heroImage: /logo.svg
heroText: 萌萌噠草頭將軍
heroFullScreen: false
tagline: 千里之行，始于足下
projects:
- icon: react
name: RaETable
desc: 一款開(kāi)箱即用的antd表格組件庫(kù)
link: https://mmdctjj.github.io/raetable
- icon: setting
name: console-loader
desc: 自動(dòng)清除其他開(kāi)發(fā)者console的loader
link: https://github.com/mmdctjj/remove-others-console-loader
footer: 萌萌噠草頭將軍?? 導(dǎo)航欄
在開(kāi)始之前你需要明確，你的導(dǎo)航欄需求是啥樣的（大白話(huà)就是哪些欄目需要在側(cè)邊欄展示，哪些在側(cè)邊欄展示）
我的思路是，根據(jù)文章的分類(lèi)，將相同的分類(lèi)文章放在同一目錄下，每個(gè)目錄對(duì)應(yīng)一個(gè)導(dǎo)航欄目。
圖片
導(dǎo)航欄的相關(guān)設(shè)置在 navbar.ts文件中。
默認(rèn)為字符串，對(duì)應(yīng) src 目錄下的文件路徑，你可以省略 .md 擴(kuò)展名，以 / 結(jié)尾的路徑會(huì)被推斷為 /README.md。
例如：
import { navbar } from "vuepress-theme-hope";
export default navbar([
"/", // 對(duì)應(yīng)首頁(yè)，即src/README.md
'/react/', // 對(duì)應(yīng)src/react/README.md
]);也可以是對(duì)象，基本格式如下：
import { navbar } from "vuepress-theme-hope";
export default navbar([
{
text: "博文",
icon: "pen-to-square",
prefix: "/posts/", // 對(duì)應(yīng) src/posts 目錄
children: [
{
text: "蘋(píng)果",
icon: "pen-to-square",
prefix: "apple/", // 對(duì)應(yīng) src/posts/apple 目錄
children: [
{ text: "蘋(píng)果1", icon: "pen-to-square", link: "1" },
{ text: "蘋(píng)果2", icon: "pen-to-square", link: "2" },
"3",
"4",
],
},
"tomato",
"strawberry",
],
},
{
text: "V2 文檔",
icon: "book",
link: "https://theme-hope.vuejs.press/zh/", // link代碼外鏈地址
},
]);我的設(shè)置為：
import { navbar } from "vuepress-theme-hope";
export default navbar([
"/",
{
text: 'React系列',
icon: 'react',
link: '/react/'
},
{
text: 'Vue系列',
icon: 'vue',
link: '/vue/'
},
{
text: 'Vite系列',
icon: 'tool',
link: '/vite/'
},
{
text: '新框架?chē)L鮮系列',
icon: 'geometry',
link: '/framework/'
},
{
text: '雜談',
icon: 'article',
link: '/posts/'
},
{
text: '標(biāo)簽',
icon: 'tag',
link: '/tag/javascript/'
},
{
text: '分類(lèi)',
icon: 'categoryselected',
link: '/category/前端/'
},
{
text: '時(shí)間軸',
icon: 'time',
link: '/timeline/'
},
]);我將一些默認(rèn)的路由也加進(jìn)了導(dǎo)航欄配置中，比如時(shí)間軸、標(biāo)簽、分類(lèi)等。
圖片
?? 側(cè)邊欄
側(cè)邊欄的配置在 sidebar.ts中
側(cè)邊欄的配置，我們可以分兩種情況：全局導(dǎo)航欄、根據(jù)每個(gè)導(dǎo)航欄欄目分離式導(dǎo)航欄。
?? 全局側(cè)邊欄配置
你可以設(shè)置側(cè)邊欄導(dǎo)航和導(dǎo)航欄的路由一一對(duì)應(yīng)，這樣就相當(dāng)于是全局的側(cè)邊欄。
對(duì)于側(cè)邊欄的具體條目，可以通過(guò)設(shè)置children: "structure"根據(jù)當(dāng)前目錄下的文件名稱(chēng)自動(dòng)生成。
import { sidebar } from "vuepress-theme-hope";
export default sidebar({
"/": [
"",
{
text: "React系列",
icon: "react",
prefix: "react/",
children: "structure",
},
{
text: "Vue系列",
icon: "vue",
prefix: "vue/",
children: "structure",
},
{
text: "Vite系列",
icon: "tool",
prefix: "vite/",
children: "structure",
},
{
text: "新框架?chē)L鮮系列",
icon: "geometry",
prefix: "framework/",
children: "structure",
},
{
text: "雜談",
icon: "study",
prefix: "posts/",
children: "structure",
},
// "intro",
// "slides",
],
});此時(shí)頁(yè)面?zhèn)冗厵谌缦聢D：
圖片
?? 分離式導(dǎo)航欄
分離式菜單配置更簡(jiǎn)潔，如下所示：當(dāng)設(shè)置structure時(shí)，默認(rèn)根據(jù)目錄下的文件自動(dòng)生成側(cè)邊欄。
import { sidebar } from "vuepress-theme-hope";
export default sidebar({
"/react/": "structure",
"/framework/": "structure",
"/vite/": "structure",
"/vue/": "structure",
"/posts/": "structure",
});
?? 自動(dòng)生成目錄頁(yè)面
另外，我們還根據(jù)文件夾下的文件列表自動(dòng)為每個(gè)文件夾生成目錄頁(yè)面。我們只需要在theme.ts中添加如下設(shè)置。
plugins: {
autoCatalog: {
index: true
},
}就可以自動(dòng)生成目錄頁(yè)面了。例如：
圖片
?? 搜索功能
該主題內(nèi)置了幾種常見(jiàn)搜索插件的支持，你只需下載你喜歡的插件和配置文件即可，我使用的是vuepress-plugin-search-pro插件，配置參考的官方配置。
plugins: [
searchProPlugin({
// 索引全部?jī)?nèi)容
indexContent: true,
// 為分類(lèi)和標(biāo)簽添加索引
customFields: [
{
getter: (page) => page.frontmatter.category as any,
formatter: "分類(lèi)：$content",
},
{
getter: (page) => page.frontmatter.tag as any,
formatter: "標(biāo)簽：$content",
},
],
}),
]效果如下：
圖片
?? 自動(dòng)部署
該主題已經(jīng)自動(dòng)添加了workflows文件，你只需添加倉(cāng)庫(kù)，修改觸發(fā)分支。
不過(guò)我在部署時(shí)遇到問(wèn)題：
Dependencies lock file is not found in /home/{username}/runners.../repository_name. Supported file patterns: package-lock.json,yarn.lock需要修改下workflows文件：去除npm cache設(shè)置
- name: 設(shè)置 Node.js
uses: actions/setup-node@v3
with:
node-version: 18
# cache: npmcicd執(zhí)行成功后，會(huì)多一個(gè)部署gh-pages分支，這是文件流中配置的，你可以修改
- name: 部署文檔
uses: JamesIves/github-pages-deploy-action@v4
with:
# 這是文檔部署到的分支名稱(chēng)
branch: gh-pages
folder: src/.vuepress/dist
圖片
接著最重要的一步，到倉(cāng)庫(kù)的設(shè)置頁(yè)面設(shè)置如下的內(nèi)容：
圖片
該設(shè)置的意思是，將選中的分支內(nèi)容部署在github自帶的頁(yè)面服務(wù)中。
接著點(diǎn)擊save按鈕，就可以去對(duì)應(yīng)的站點(diǎn)訪(fǎng)問(wèn)了。
我的站點(diǎn)：https://mmdctjj.github.io/blogs2/
?? 添加評(píng)論功能
不同的插件，評(píng)論的實(shí)現(xiàn)原理不同，我接觸過(guò)最早的原理是通過(guò)將評(píng)論信息映射到倉(cāng)庫(kù)的issue中。
然而，后來(lái)開(kāi)始流行Discussions，這也是vuepress-theme-hope推薦的方式，
?
如果你的博客面向程序員，請(qǐng)使用Giscus，面向大眾請(qǐng)選擇Waline, 所以我選擇了Giscus
?
首先需要你創(chuàng)建一個(gè)空的倉(cāng)庫(kù)。其次，由于評(píng)論需要用戶(hù)登錄到GitHub，所以，我們還需要提供登錄應(yīng)用的服務(wù)。
這里我們不用擔(dān)心，因?yàn)镚ithub為我們提供了簡(jiǎn)單的登陸應(yīng)用的功能：giscus,
首先安裝Giscus：https://github.com/apps/giscus
圖片
點(diǎn)擊install按鈕，在配置詳情頁(yè)中選擇對(duì)應(yīng)的生效倉(cāng)庫(kù)。（這里我選擇僅僅對(duì)評(píng)論倉(cāng)庫(kù)生效）
圖片
然后回到評(píng)論倉(cāng)庫(kù)，點(diǎn)擊seething，選中Feature下的Discussions。
圖片
點(diǎn)擊set up discussions，默認(rèn)的文本不需要修改，點(diǎn)擊提交即可出現(xiàn)如下頁(yè)面，說(shuō)明該功能啟用成功。
圖片
接著，我們前往https://giscus.app/zh-CN 設(shè)置你的倉(cāng)庫(kù)和分類(lèi)。
圖片
圖片
在啟用欄目復(fù)制以下幾個(gè)信息。
圖片
接著將以下信息復(fù)到theme.ts即可：
plugins: {
comment: {
// You should generate and use your own comment service
provider: "Giscus",
repo: "mmdctjj/blogs-comments",
repoId: "xxxx", // 替換下
category: "Announcements",
categoryId: "xxxx" // 替換下
},
}此時(shí)當(dāng)我們?cè)u(píng)論之后，在評(píng)論倉(cāng)庫(kù)查看，
圖片
?? 最后
vuepress-theme-hope 主題通過(guò)默認(rèn)的配置就提供了豐富的開(kāi)箱即用的功能，使得配置體驗(yàn)相比較與vuepress-theme-reco有了明顯的提升。這是我替換博客主題最大的體驗(yàn)。
