1 前言

虽然目前的个人网站上对应的 blog 页面，但是只能通过在右侧标签云里面进行选择的方式进行筛选，点击之后也是进入外链，因此我想着能不能再创建一个静态网页来查看自己学习过程中记录下来的笔记，最好启动速度要快，样式要符合个人的审美，最终选择了 VitePress 来搭建一个静态网页。

通过下面的内容，你也可以从 0 到 1 使用 VitePress 搭建一个个人博客。

2 快速上手

2.1 启动项目

可以查看资料中的官网链接，官网链接中有详细的启动项目的流程，我们也就是有样学样的来实现一下吧。

官网中使用的 yarn 启动的项目，我这里使用 npm 来项目的初始化和启动，依次键入下面的代码就可以完成项目的创建了。

mkdir DevGuide && cd DevGuide
npm init
npm add vitepress -D
mkdir docs && echo '# Hello VitePress' > docs/index.md

项目创建完成之后就需要启动该项目，需要在package.json添加以下scripts。

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

使用npm run docs:dev对项目进行启动，你就可以得到下面的内容。

但是单独看这个界面还是太单调了，如果你去网上看别人创建的还有首页，右上角也有好多个标签栏，因此还需要把该项目重新初始化一下。

npm exec vitepress init

构建完成之后你会发现你的网页结构和文件结构都发生了变化，网页中多了首页，右上角也多了其他的标签栏。

2.2 配置介绍

在创建好了之后就是添加页面，修改页面样式了，但是每一个配置是怎么样的呢，我这边采用的 CV 大法，直接打开 VitePress 的 github 代码，把他中文文档的代码直接复制下来，然后对着他自己的官网来看就好了，不管是文件结构什么的都可以直接参考官网的写法

这已经和官网长的一模一样了，不过还是需要修改，至少需要知道怎么改，这样才可以改成自己想要的样子，同时文档的路径什么的也需要注意一下。

2.3 搜索功能

如果你希望你的文档带一个搜索功能，VitePress 提供了两种方式，一种是使用 algolia 的方式，需要去algolia 注册一个账号，然后使用他们提供的相关配置就可以了，如何你点击搜索就相当于像其发送请求，然后他返回回来搜索结果，我们这里先来尝试采用本地搜索的方式。

要使用本地搜索只需要在 config 文件下面添加下面的代码就可以了，可以在 options 参数中设置显示的内容，如果是多语言的话，就把 options 参数部分放在下面的 locales 中。

themeConfig: {
  search: {
    provider: "local",
    options: {
      translations: {
        button: {
          buttonText: "搜索文档",
          buttonAriaLabel: "搜索文档",
        },
        modal: {
          noResultsText: "无法找到相关结果",
          resetButtonTitle: "清除查询条件",
          footer: {
            selectText: "选择",
            navigateText: "切换",
          },
        },
      },
      // locales: {},
    },
  },
}

使用了上面的代码之后你就有了本地搜索功能了，可能不是很够用，但是看着还行，点击右侧的展开按钮还可以查看具体匹配的部分是什么。

但是在使用过程中，我发现了一些问题，对于中文文档来说他的支持可能并没有那么好，你可以看见下面的搜索结果中显示的是没有这个搜素结果，但是直接看页面，你会发现有无数多个学习，我也不知道是什么情况，但是我并没有打算搞懂他，因为我打算只用 aligolia。

首先你需要在他的官网中进行申请，填写上你已经部署好的网站链接和你的邮箱，如果还没部署需要先部署一下。

之后就是等待就可以了，会发送一封邮件到你填写的邮箱中，里面有需要的配置，需要注意的是，点击申请按钮需要连梯子，不然可能会提交不了。

等待两到三天官方就会发送来邮件，之后你只需要按照他的步骤来操作即可，不过下面我也会展示我操作的细节。

themeConfig: {
  search: {
    provider: "algolia",
    options: {
      appId: "M37AYU4B3I",
      apiKey: "2d22dbbcb3736eaba",
      indexName: "wyx-hhhhio",
      placeholder: "搜索文档",
      translations: {
        button: {
          buttonText: "搜索文档",
          buttonAriaLabel: "搜索文档",
        },
        modal: {
          searchBox: {
            resetButtonTitle: "清除查询条件",
            resetButtonAriaLabel: "清除查询条件",
            cancelButtonText: "取消",
            cancelButtonAriaLabel: "取消",
          },
          startScreen: {
            recentSearchesTitle: "搜索历史",
            noRecentSearchesText: "没有搜索历史",
            saveRecentSearchButtonTitle: "保存至搜索历史",
            removeRecentSearchButtonTitle: "从搜索历史中移除",
            favoriteSearchesTitle: "收藏",
            removeFavoriteSearchButtonTitle: "从收藏中移除",
          },
          errorScreen: {
            titleText: "无法获取结果",
            helpText: "你可能需要检查你的网络连接",
          },
          footer: {
            selectText: "选择",
            navigateText: "切换",
            closeText: "关闭",
            searchByText: "搜索提供者",
          },
          noResultsScreen: {
            noResultsText: "无法找到相关结果",
            suggestedQueryText: "你可以尝试查询",
            reportMissingResultsText: "你认为该查询应该有结果？",
            reportMissingResultsLinkText: "点击反馈",
          },
        },
      },
    }  
  }
}

和上面的内容类似，只需要修改 provider 为 algolia，并在 options 中添加对应的内容对应的 apiId、apiKey和IndexName，这些内容都可以在官方发送的邮箱中查看到。

点击邮箱中的该链接就可以进入爬虫控制台，里面可以查看爬虫的概况和编辑控制器的配置等，同时也可以直接点击重新爬取网站。

同时还有一个需要注意的点，就是你可能会发现无法实时的搜索到你的新文件，例如该文档是我临时创建的，而 algolia 还没有进行爬取，因此无法获取到该页面的内容，并且即使我们部署上线了，他也不能搜索到，因此他的服务器是每周定时爬取的，他没爬取你就搜索不到，那么需要怎么样才可以我完成部署后他就执行爬取操作呢。

首先你需要先了解 GitHub Page 是如何部署，可以先查看4.1 GitHub Page 部署部分的内容，最好是部署了一遍后在回头来看这部分的内容。

打开对应存储库的 Settings > Secrets and variables > Actions > Repository secrets，点击创建新的 repository secret，在里面添加上 API_KEY 和 APPLICATION_ID，里面填写上对应的内容。

name: algolia
on:
  push:
    branches:
      - main
jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Get the content of algolia.json as config
        id: algolia_config
        run: echo "config=$(cat crawlerConfig.json | jq -r tostring)" >> $GITHUB_OUTPUT
      - name: Push indices to Algolia
        uses: signcl/docsearch-scraper-action@master
        env:
          APPLICATION_ID: ${{ secrets.APPLICATION_ID }}
          API_KEY: ${{ secrets.API_KEY }}
          CONFIG: ${{ steps.algolia_config.outputs.config }}

假设你以为完成了页面的 Github Page 的部署，那么你的项目文件夹下应该有/.github/workflows 文件夹，如果没有就创建一个，在该文件夹下新建 algoloa.yml文件，在文件中写入上面的内容。

{
    "index_name": "wyx-hhhhio",
    "start_urls": [
        "https://wyx-hhhh.github.io/DevGuide/"
    ],
    "rateLimit": 8,
    "maxDepth": 10,
    "selectors": {
        "lvl0": {
            "selector": "",
            "defaultValue": "Documentation"
        },
        "lvl1": ".content h1",
        "lvl2": ".content h2",
        "lvl3": ".content h3",
        "lvl4": ".content h4",
        "lvl5": ".content h5",
        "content": ".content p, .content li"
    },
    "selectors_exclude": [
        "aside",
        ".page-footer",
        ".next-and-prev-link",
        ".table-of-contents"
    ],
    "js_render": true
}

在项目的根路径下创建一个 crawlerConfig.json文件，写入上面的内容，并修改前两个 key 对应的 value，修改为自己的内容。

两个文件创建完成之后，就只需要推送到 main 节点即可，推送上去就会自动抓取了。当然我也内容对你不一定有效，我会把我参考的一些资料放在最后。

**2024.6.20 更新
**忽然搜索不出来了，也不知道是怎么回事，搞了很久没搞好，改回 local 搜索了。

2.4 Markdown 扩展

直接参考下面的官方文档就可以了。

vitepress.dev/zh/guide/ma…

3 自定义功能

3.1 自定义组件

可以参考下面的官方文档中的内容，下面我也会自己做一个演示。

vitepress.dev/zh/guide/us…

自己新建一个 components文件夹，在下面创建 home.vue文件后在里面使用 vue 语法写上内容，在在需要使用他的地方引用即可。

通过上面的操作，你就可以实现对自定义组件了，现在去网页上看一下效果吧。

3.2 自定义样式

首先先来自定义一下主题色，或者直接使用原来的主题色不进行替换也可以，修改的文件就在/.vitepress/theme/style.css中，主要修改--vp-c-brand部分，例如修改为下面的形式。

:root {
  --vp-c-default-1: var(--vp-c-gray-1);
  --vp-c-default-2: var(--vp-c-gray-2);
  --vp-c-default-3: var(--vp-c-gray-3);
  --vp-c-default-soft: var(--vp-c-gray-soft);

  --vp-c-brand-1:#36AD6AFF;
  --vp-c-brand-2: rgb(11, 150, 76);
  --vp-c-brand-3: #18A058FF; 
  --vp-c-brand-soft: rgba(45, 164, 97, 0.11);

  --vp-c-tip-1: var(--vp-c-brand-1);
  --vp-c-tip-2: var(--vp-c-brand-2);
  --vp-c-tip-3: var(--vp-c-brand-3);
  --vp-c-tip-soft: var(--vp-c-brand-soft);

  --vp-c-warning-1: var(--vp-c-yellow-1);
  --vp-c-warning-2: var(--vp-c-yellow-2);
  --vp-c-warning-3: var(--vp-c-yellow-3);
  --vp-c-warning-soft: var(--vp-c-yellow-soft);

  --vp-c-danger-1: var(--vp-c-red-1);
  --vp-c-danger-2: var(--vp-c-red-2);
  --vp-c-danger-3: var(--vp-c-red-3);
  --vp-c-danger-soft: var(--vp-c-red-soft);
}