第一次使用vitepress搭建笔记/说明文档¶
约 1413 个字 • 126 行代码
起因¶
由于想在CS61A完成作业的仓库中把笔记放上，
并且之前又看到了不同的几个网站上都使用了很相似的网页的框架
(由于在这些网站上都没有找到关于生成的框架的信息)于是开始搜索可能的框架，
发现vitepress¶
由于之前有同学和我提到了vue，于是先去搜索了一下vue，发现好像vue用于写界面的东西，
然后发现了vuepress这个东西，
然后看了一下官方说明文档显示的效果，感觉有点类似 但又好像不完全和上面那几个网页一样，
于是我以为是有其他的主题，于是在github上找到了hope这个主题
主页 | vuepress-theme-hope (vuejs.press)
但尝试安装时试了好一会都没有成功能够预览，并且也似乎和那几个网站有不一样的地方(感觉不是用这个框架生成)，所以开始继续查看其他的框架。
然后在搜索时就发现了vitepress这个东西，并从某篇文章上了解到vitepress和vuepress都是出自同一个大佬之手，
于是开始查看vitepress的官网，
VitePress | 由 Vite 和 Vue 驱动的静态站点生成器
然后发现，那几个网站应该就是用vitepress生成的，于是就按照 快速开始 尝试安装，并很容易就安装上并且能预览初始的页面了，
所以打算尝试用vitepress来搭建笔记的网站。
摸索基本的设置¶
按照 站点配置 | VitePress 开始进行配置，
如果是部署在github上，需要将
base改成仓库名，如
然后继续按照官方文档配置了导航栏和侧边栏
中文显示文字设置¶
在配置网站搜索功能的时候，由于默认显示的文字都是英文， 想改成中文，
但是按照 这里 的示例配置，发现不能修改默认的显示文字(应该是能修改多语言版本的显示效果)，然后想到了官方文档中是已经显示成中文了，所以前去官方文档的github仓库的设置查看作者的现成的设置😉，
然后，在 index.ts 中查看，发现了设置默认网页的显示文字需要使用 root ，
在 zh.ts 中找到了相应的搜索的文字设置，但作者用的搜索引擎不是 local 所以他的这些配置我不能用，但是他其他的网页文字的配置感觉可以直接用，于是我就复制到了我的 config.mts 中，而搜索的文字就使用了官方文档中的设置，最后
export default defineConfig({
...
themeConfig: {
...
footer: {
message: '基于 <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/">CC BY-NC-SA 4.0</a> 许可发布',
copyright: `版权所有 © 2024-${new Date().getFullYear()} <a href="https://github.com/RonaldLN">Ronald Luo</a>`
},
docFooter: {
prev: '上一页',
next: '下一页'
},
outline: {
label: '页面导航'
},
lastUpdated: {
text: '最后更新于',
formatOptions: {
dateStyle: 'short',
timeStyle: 'medium'
}
},
langMenuLabel: '多语言',
returnToTopLabel: '回到顶部',
sidebarMenuLabel: '菜单',
darkModeSwitchLabel: '主题',
lightModeSwitchTitle: '切换到浅色模式',
darkModeSwitchTitle: '切换到深色模式',
search: {
provider: 'local',
options: {
locales: {
root: {
translations: {
button: {
buttonText: '搜索文档',
buttonAriaLabel: '搜索文档'
},
modal: {
noResultsText: '无法找到相关结果',
resetButtonTitle: '清除查询条件',
footer: {
selectText: '选择',
navigateText: '切换'
}
}
}
}
}
}
}
},
})
设置网页图标(摸索出了亮暗模式的设置方法)¶
从官方文档上了解到，
网页页面左上角的图标 logo 是用 logo 设置，
而网页标签上的图标，是在 head 中设置，
然后下载了一个svg图标
尝试按照官方文档进行设置，但是发现，由于我的浏览器设置的是暗模式，而这个图标本身也是黑色的，所以在网页上显示不太明显，
摸索尝试了一下，发现 logo 中有 light 和 dark 的设置，能设置不同模式下的图标，
于是开始搜索如何修改svg图片的颜色，然后在这篇文章中找到了修改svg颜色的方法，
修改颜色需要在 <path> 中添加 fill 参数，即
而网页标签的图标，由于根据官方文档中的解释，
会被渲染成
所以我认为应该是需要添加html的参数，于是进行搜索，然后在这篇文章中找到了相应的方法
Favicon That Works for Light and Dark Mode (joyofcode.xyz)
html中是需要添加 media="(prefers-color-scheme: [light | dark])"
那么在 config.mts 中就应该写成
export default defineConfig({
...
head: [
['link', { rel: 'icon', href: '/CS-61A-Fall-2020/notebook-outline.ico', media: '(prefers-color-scheme: light)' }],
['link', { rel: 'icon', href: '/CS-61A-Fall-2020/notebook-outline-white.ico', media: '(prefers-color-scheme: dark)' }],
],
})
然后进行预览，发现成功能显示不同的颜色了😄
发现home主页 features 能添加链接¶
想在 features 对应的卡片上，添加能跳转的链接，于是就尝试了看看能不能添加 link 参数，发现居然真的可以😮
配置mermaid¶
由于官方基本的设置好像并没有提供mermaid画图的支持，所以搜索了一下如何在vitepress中使用mermaid，然后找到了
VitePress Plugin Mermaid | Mermaid support for vitepress (emersonbottero.github.io)
但是在看这个插件的说明文档的 Setup it up 没看懂要如何设置，然后想到这个官方文档上就使用了mermaid，所以可以参考它的配置，
于是去它的github仓库的配置文件查看，然后发现，是需要将原来的
改成下面这样即可
import { defineConfig } from 'vitepress'
import { withMermaid } from "vitepress-plugin-mermaid"
export default withMermaid(
defineConfig({
...
})
)
然后预览发现能显示mermaid的图了😄
需要修改的格式¶
在预览时发现，vitepress不支持用 == 来显示高亮，于是搜索html的高亮方法，发现需要使用 <mark> 标签( <mark>...</mark> )
完成的笔记网页¶
后记¶
闲来无事搜索vitepress能不能写blog(本来以为不能，因为官方文档上并没有关于blog的相关设置)，然后发现了vitepress blog，
VitePress Blog | VitePress Blog Theme
似乎是基于vitepress开发的一个能写blog的主题(或者说扩展模块)，
这是官方文档中的blog首页
VitePress Blog | VitePress Blog
感觉效果看起来还蛮不错，打算之后试试
创建日期: 2024-03-14