基于Markdown的文档网站生成工具-VitePress框架

基于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’ 这个图标,那么在你的配
置中使用它的话,页面上是无法正确显示图标的。

为了解决这个问题,有几种方法:

1. 使用 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 类名。

2. 【推荐该方式】使用自定义的 SVG 图标:
   可以使用自定义的 SVG 图标,也可以继续使用 { svg: string } 的形式进行定义和使用。