{T}

简介

VitePress

VitePress 是一个基于 Vite 和 Vue 的静态站点生成器 (SSG)，专为构建快速、以内容为中心的网站而设计。它具有以下特点：

  • Vite 驱动：即时服务器启动，始终立即反映 (<100ms) 编辑变化，无需重新加载页面
  • 内置 Markdown 扩展：frontmatter、表格、语法高亮……应有尽有。特别是 VitePress 提供许多用于处理代码块的高级功能
  • Vue 增强的 Markdown：每个 Markdown 页面都是 Vue 单文件组件，可以使用 Vue 模板语法或导入的 Vue 组件在静态内容中嵌入交互性

VuePress 是基于 Vue 2 和 webpack。，但 VitePress 是借 Vue 3 和 Vite 的

性能对比

VitePress 生成的网站在初次访问时提供静态 HTML，但它变成单页应用程序（SPA）进行站点内的后续导航

  • 快速的初始加载

    对任何页面的初次访问都将会是静态的、预呈现的 HTML，以实现极快的加载速度和最佳的 SEO。然后页面加载一个 JavaScript bundle，将页面变成 Vue SPA (这被称为“激活”)。与 SPA 激活缓慢的常见假设不同，由于 Vue 3 良好的原始性能和编译优化，这个过程实际上非常快

  • 加载完成后可以快速切换

    更重要的是，SPA 模型在首次加载后能够提升用户体验。用户在站点内导航时，不会再触发整个页面的刷新。而是通过获取并动态更新页面的内容来实现切换。VitePress 还会自动预加载视口范围内链接对应的页面片段。这样一来，大部分情况下，用户在加载完成后就能立即浏览新页面

  • 高效的交互： 每个 Markdown 页面都被处理为 Vue 组件并编译成 JavaScript

快速开始

VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：

bash
npm init -y

pnpm add -D vitepress@next

# 命令行设置向导
pnpm vitepress init

VitePress 是仅支持 ESM 的软件包。不要使用 require() 导入它，并确保最新的 package.json 包含 "type": "module"，或者更改相关文件的文件扩展名，例如 .vitepress/config.js 到 .mjs/.mts

将需要回答几个简单的问题：

sh
┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Where should VitePress look for your markdown files?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing.

假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：

sh
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.mts
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中

配置文件

配置文件 (.vitepress/config.js) 能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

JavaScript
export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

路由

VitePress 使用基于文件的路由，生成的 HTML 页面是从源 Markdown 文件的目录结构映射而来的。假定以下目录结构：

code
.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

生成的 HTML 页面会是这样：

sh
index.md                  -->  /index.html (可以通过 / 访问)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md  -->  /guide/getting-started.html

在页面之间链接时，可以使用绝对路径和相对路径。注意，虽然 .md 和 .html 扩展名都可以使用，但最佳做法是省略文件扩展名，以便 VitePress 可以根据配置生成最终的 URL

markdown
<!-- Do -->
[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)

<!-- Don't -->
[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)

要链接到站点中不是由 VitePress 生成的页面，需要使用完整的 URL（在新选项卡中打开）或明确指定 target：

python
[Link to pure.html](/pure.html){target="_self"}

注意：在 Markdown 链接中，base 会自动添加到 URL 前面。这意味着，如果想链接到 base 之外的页面，则链接中需要类似 ../../pure.html 的内容（由浏览器相对于当前页面解析）。或者直接使用锚标记语法：<a href="/pure.html" target="_self">Link to pure.html</a>

部署

运行命令来构建文档：

bash
npm run docs:build

# 预览
npm run docs:preview

preview 命令是启动本地静态 Web 服务 http://localhost:4173，该服务以 .vitepress/dist 作为源文件。通过传递 --port 作为参数来配置服务器的端口

json
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}

设定 public 根目录

默认情况下，假设站点将部署在域名 / 的根路径上。如果站点在子路径中提供服务，例如 https://mywebsite.com/blog/，则需要在 VitePress 配置中将 base 选项设置为 '/blog/'

JavaScript
export default {
  base: '/base/'
}

Nginx 部署

下面是一个 Nginx 服务器块配置示例。此配置包括对基于文本的常见资源的 gzip 压缩、使用适当缓存头为 VitePress 站点静态文件提供服务的规则以及处理 cleanUrls: true 的方法

nginx
server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    listen 80;
    server_name _;
    index index.html;

    location / {
        # content location
        root /app;

        # exact matches -> reverse clean urls -> folders -> not found
        try_files $uri $uri.html $uri/ =404;

        # non existent pages
        error_page 404 /404.html;

        # a folder without index.html raises 403 in this setup
        error_page 403 /404.html;

        # adjust caching headers
        # files in the assets folder have hashes filenames
        location ~* ^/assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

本配置默认已构建的 VitePress 站点位于服务器上的 /app 目录中。如果站点文件位于其他位置，请相应调整 root 指令

不要默认为 index.html。try_files 解析不能像其他 Vue 应用那样默认为 index.html。这会导致页面状态处于无效