VuePress

链接

• VuePress 官方文档 (opens new window)
• VitePress 官方文档 (opens new window)
• VitePress 快速上手中文教程 (opens new window)

视频推荐

VuePress 搭建教程 -飞跃高山与大洋的鱼 (opens new window)

vuepress-plugin-fulltext-search

vuepress-plugin-fulltext-search (opens new window)是一个 VuePress 的搜索插件，使用Flexsearch (opens new window)库为 VuePress 提供全文搜索功能

用法

安装插件

npm i vuepress-plugin-fulltext-search -D
#or
yarn add vuepress-plugin-fulltext-search -D

在 docs/.vuepress/config.js中添加以下内容：

// docs/.vuepress/config.js
module.exports = {
  // ...
  plugins: ["fulltext-search"],
};

插件已经安装完成，编译后即可查看效果

搜索参数

示例如下：

https://your-website.com?query=hello+world

从搜索中排除页面

如果不想让某页面在搜索时出现，可以在该页面的开头添加search: false

示例如下：

---
search: false
---

VitePress 快速部署

VitePress 和 VuePress 一样，是一个静态网页生成器。简而言之，VitePress 可以把用 Markdown 编写的内容转化为可以轻松部署到任何地方的静态 HTML 页面。

1. 创建项目

创建并更改为新目录

mkdir vitepress-starter && cd vitepress-starter

然后，初始化包管理器

yarn init

2. 安装 VitePress

添加 VitePress 和 Vue 作为项目的开发依赖项

yarn add --dev vitepress vue

3. 启动开发环境

创建一个文档，用于测试

mkdir docs && echo '# Hello VitePress' > docs/index.md

在项目根目录中创建文件package.json

.
├─ docs
│  └─ index.md
└─ package.json

在文件package.json中添加

"scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs",
    "deploy": "bash deploy.sh"
  },

通过本地服务器展示文档

yarn docs:dev

通过访问链接http://localhost:5173查看网页

4. 配置文件

在docs目录中创建一个名称为.vitepress目录，并在.vitepress中创建文件config.js

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json

在文件config.js中添加一些基本信息

export default {
  title: "VitePress",
  description: "Just playing around.",
};

5. 部署到 GitHub

在 GitHub 中创建一个新项目，并在项目的设置中开启 GitHub Pages

新建文件deploy.sh，并把以下内容填写在文件中

#!/usr/bin/env sh

# 忽略错误
set -e

# 构建
npm run docs:build

# 进入待发布的目录
cd docs/.vitepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

#以下内容需要填写新建项目的SSH

# 如果部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果是部署到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

如果项目名称不是youname.github.io这样的形式，就需要在config.js文件中配置 base，如下

export default {
  base: "/docs/",
};

最后，部署到 GitHub 上

yarn deploy

更多请参考官方文档 (opens new window)

样式美化

方法一

在 .vitepress 中新建文件夹 theme ，在theme目录下新建文件 index.ts ，再在 theme目录下新建 style 文件夹，然后在文件夹 style 中新建文件 index.css 和 var.css

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.mts
│  │  └─ theme
|  |     └─ index.ts
│  │     └─ style
│  │        └─ index.css
│  │        └─ var.css
│  └─ index.md
└─ node_modules

/* index.ts */
import DefaultTheme from "vitepress/theme";
import "./style/index.css";

export default {
  extends: DefaultTheme,
  // ...DefaultTheme, //或者这样写也可
};

/* index.css */
@import "./var.css";

现在你可以在var.css中写入你要修改的样式，以对原本的样式进行覆盖

方法二

最简单修改样式的方法就是直接在 index.md 中插入代码

<style>
/* 这里添加修改样式的css代码 */
</style>

更多内容参考VitePress 快速上手中文教程-样式美化 (opens new window)

问题

PWA 更新缓慢问题

在VuePress中可以通过安装PWA 插件，使网页可以离线访问。但我在使用一段时间后发现了 PWA 的一些问题，每次提交新的内容后打开网页，都需要等待一段时间才会弹出更新弹窗，甚至有时候等好长时间都无法弹出更新弹窗

首先确定网站是否可以正常访问

注意

由于 PWA 会使浏览器缓存网页从而实现离线访问，所以无法直接判断网站是否可以访问。可以使用其他浏览器或设备访问网站，从而判断网站是否可以访问。由于浏览器的隐私模式不会保存网页缓存，所以我们也可以利用这一特性访问网页，判断网页是否可以正常访问。

如果网页可以正常访问，继续判断是否是Service Workers出现了问题

在service-worker.js中有一行代码是；

importScripts(
  "https://storage.googleapis.com/workbox-cdn/releases/4.3.1/workbox-sw.js"
);

有可能是代码中的链接无法访问的导致的，使用浏览器访问该链接 (opens new window)，查看是否可以访问。

该链接中的内容如下：

workbox-sw.js

!(function () {
  "use strict";
  try {
    self["workbox:sw:4.3.1"] && _();
  } catch (t) {}
  const t = "https://storage.googleapis.com/workbox-cdn/releases/4.3.1",
    e = {
      backgroundSync: "background-sync",
      broadcastUpdate: "broadcast-update",
      cacheableResponse: "cacheable-response",
      core: "core",
      expiration: "expiration",
      googleAnalytics: "offline-ga",
      navigationPreload: "navigation-preload",
      precaching: "precaching",
      rangeRequests: "range-requests",
      routing: "routing",
      strategies: "strategies",
      streams: "streams",
    };
  self.workbox = new (class {
    constructor() {
      return (
        (this.v = {}),
        (this.t = {
          debug: "localhost" === self.location.hostname,
          modulePathPrefix: null,
          modulePathCb: null,
        }),
        (this.s = this.t.debug ? "dev" : "prod"),
        (this.o = !1),
        new Proxy(this, {
          get(t, s) {
            if (t[s]) return t[s];
            const o = e[s];
            return o && t.loadModule(`workbox-${o}`), t[s];
          },
        })
      );
    }
    setConfig(t = {}) {
      if (this.o)
        throw new Error(
          "Config must be set before accessing workbox.* modules"
        );
      Object.assign(this.t, t), (this.s = this.t.debug ? "dev" : "prod");
    }
    loadModule(t) {
      const e = this.i(t);
      try {
        importScripts(e), (this.o = !0);
      } catch (s) {
        throw (console.error(`Unable to import module '${t}' from '${e}'.`), s);
      }
    }
    i(e) {
      if (this.t.modulePathCb) return this.t.modulePathCb(e, this.t.debug);
      let s = [t];
      const o = `${e}.${this.s}.js`,
        r = this.t.modulePathPrefix;
      return (
        r &&
          "" === (s = r.split("/"))[s.length - 1] &&
          s.splice(s.length - 1, 1),
        s.push(o),
        s.join("/")
      );
    }
  })();
})();
//# sourceMappingURL=workbox-sw.js.map

如果链接正常可以尝试切换网络重试，如果链接不能正常访问，可能是 DNS 出现了问题。例如，DNS 劫持或 DNS 污染，可以更换网络后再尝试，或者使用代理或 VPN 的方式解决

VitePress 本地搜索不显示

我根据VitePress的官方文档在index.ts中添加了以下代码，但搜索框并没有显示出来

/* index.ts */
export default {
  search: {
    provider: "local",
  },
};

在网上寻找许久后发现需要安装插件

npm i vitepress-plugin-search markdown-it flexsearch -D

安装插件后样式有可能会发生变化，需要在.vitepress/theme/styles/index.css下重新修改样式