基于Markdown的文档网站生成工具-VitePress框架
文章目录
- 基于Markdown的文档网站生成工具-VitePress框架
- 什么是VitePress
- VitePress对比docsify
- 安装和使用
- 安装
- 源文件
- 运行和构建
- 工作常用总结
- config.mts 配置文件'telegram' 这个图标
基于Markdown的文档网站生成工具-VitePress框架
什么是VitePress
官网：https://vitepress.dev/
VitePress vitePress是由vite+vue驱动的静态页面生成器，专为构建快速、以内容为中心的站点而设计。
VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。
VitePress对比docsify
VitePress 和 docsify 都是非常流行的轻量级文档网站生成工具,主要区别如下:
- 原理不同:
- VitePress 基于 VuePress,通过 Vite 构建生成静态网站。
- docsify 直接通过在网页中动态渲染 Markdown 内容。
- 特性不同:
- VitePress 支持 Vue 组件,Markdown 扩展,主题定制等更丰富的特性。
- docsify 更简单轻量,但定制能力较弱。
- 性能不同:
- VitePress 通过预构建,页面加载速度更快。
- docsify 是运行时动态渲染,页面加载相对缓慢。
- 使用难易不同:
- VitePress 需要了解一定的 Vue 和构建工具使用。
- docsify 可以零配置使用,更容易上手。
- 社区支持不同:
- VitePress 基于 VuePress,生态更完善。
- docsify 生态相对较小。
总体来说,VitePress 更强大完善,但也更重一些。如果需要构建复杂文档站点,VitePress会更合适。而docsify更适合简单轻量的文档。
所以可以根据实际文档网站的需求来选择合适的工具。如果需要定制能力,VitePress可能优先考虑;如果追求极简使用,则可以选择docsify。
总结：VitePress 更强大完善。
安装和使用
安装
VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：
npm add -D vitepress
VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。
npx vitepress init
文件结构
如果正在构建一个独立的 VitePress 站点，可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。
假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中。也可以手动配置这些位置。
源文件
.vitepress 目录之外的 Markdown 文件被视为源文件。
VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。
生成的 HTML 页面是从源 Markdown 文件的目录结构映射而来的。例如，给定以下目录结构：
.
├─ guide
│ ├─ getting-started.md
│ └─ index.md
├─ index.md
└─ prologue.md
生成的 HTML 页面会是这样：
index.md --> /index.html (可以通过 / 访问)
prologue.md --> /prologue.html
guide/index.md --> /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md --> /guide/getting-started.html
项目根目录
项目根目录是 VitePress 将尝试寻找 .vitepress 特殊目录的地方。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的预留位置。
当从命令行运行 vitepress dev 或 vitepress build 时，VitePress 将使用当前工作目录作为项目根目录。要将子目录指定为根目录，需要将相对路径传递给命令。例如，如果 VitePress 项目位于 ./docs，应该运行 vitepress dev docs
运行和构建
查看 package.json，知道都有哪些命令。
其中，构建构建输出存储在 .vitepress/dist 中
工作常用总结
config.mts 配置文件’telegram’ 这个图标
配置文件始终从<root>/.vitpress/config.[ext]解析。
[ext]是支持的文件扩展名之一。支持开箱即用的TypeScript。支持的扩展包括.js、.ts、.cjs、.mjs、.cts和.mts。
默认的config.mts 文件是 VitePress 的配置文件,它定义了你的 VitePress 站点的各种设置和属性。
使用 themeConfig.socialLinks 可以配置社交链接，目前支持的有：
export type SocialLinkIcon =| 'discord'| 'facebook'| 'github'| 'instagram'| 'linkedin'| 'mastodon'| 'npm'| 'slack'| 'twitter'| 'x'| 'youtube'| { svg: string }
如果 VitePress 默认没有预定义 ‘telegram’ 这个图标,那么在你的配
置中使用它的话,页面上是无法正确显示图标的。
为了解决这个问题,有几种方法:
- 使用 Font Awesome 或其他图标库提供的 Telegram 图标:
npm install @fortawesome/fontawesome-free
首先在你的项目中安装所需的图标库,例如 npm install @fortawesome/fontawesome-free
然后在你的 VitePress 配置中,将 ‘telegram’ 映射到对应的图标类名:
export default defineConfig({ themeConfig: { socialLinks: [ { icon: 'fab fa-telegram', link: 'https://t.me/mini_boost_devnet_bot' } ] }
})
经过测试发现不行， 原因是 VitePress 的 SocialLinkIcon 类型中,icon 属性只接受预定义的字符串类型或者 { svg: string } 这种对象类型。它不支持直接使用 Font Awesome 等库提供的 CSS 类名。
- 【推荐该方式】使用自定义的 SVG 图标:
可以使用自定义的 SVG 图标,也可以继续使用 { svg: string } 的形式进行定义和使用。