快速上手

Mirco_Akira2025年3月9日大约 4 分钟

注意

本站为mirco文档站迁移升级版，部分内容没有迁移

您可通过此链接访问旧版文档站：旧版文档入口

该项目是如何开发的

提示

这里本来是想写使用教程的，但目前并没有加入自己的功能，也没什么好写的

就分享一下开发教程，以及开发过程中的问题（或许之后会单独写一个板块？）

不想了解可以略过此处

项目采用 vuepress v2 作为框架，使用 vuepress-theme-hope 主题
具体使用文档在各自的官网都非常详细

Q：为何放弃了之前版本的开发？
A：因为旧版文档站是使用vuepress v1开发的，在使用部分插件后页面显示出现了标题重复的问题，同时我发现vuepress v2功能更加强大，于是迁移到了v2版本。

不过一些插件的使用可能会有些细节没有提到，下面就会教你如何使用部分插件

搜索插件（Algolia DocSearch）

提示

vuepress-theme-hope教程地址
vuepress 默认支持多种搜索插件，我个人认为DocSearch插件搜索的结果最好，但配置可能比较麻烦

安装 @vuepress/plugin-docsearch 插件

# 这里2.0.0-rc.82是版本号，根据你自己vuepress版本下载对应的版本，防止出现问题
pnpm add -D @vuepress/plugin-docsearch@2.0.0-rc.82

在Algolia官网申请加入 DocSearch
根据要求填写即可，申请链接
申请之后会收到一封邮件，耐心等待一天左右就会收到回复
回复邮件中会提供 appId、apiKey、indexName，但此时请不要着急，请跟着下一步进行配置

对Algolia 爬虫进行配置

这一步特别重要，如果你使用了主题，Algolia官方默认的配置会出现查询不到任何 records 的情况

首先如果你没有Algolia账号，请在你收到的邮件里面点击 "Accept this invitation to get started!"
然后进入 Algolia Dashboard
进入 Crawler（爬虫）页面，点击 "Editor"
修改配置（配置内容来自vuepress-theme-hope，部分内容需要根据项目进行修改）

  new Crawler({
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_API_KEY",
      rateLimit: 8,
      startUrls: [
      // 这是 Algolia 开始抓取网站的初始地址
      // 如果你的网站被分为数个独立部分，你可能需要在此设置多个入口链接
      "https://YOUR_WEBSITE_URL/",
      ],
      sitemaps: [
      // 如果你在使用 Sitemap 插件 (如: @vuepress/plugin-sitemap)，你可以提供 Sitemap 链接
      "https://YOUR_WEBSITE_URL/sitemap.xml",
      ],
      ignoreCanonicalTo: false,
      exclusionPatterns: [
      // 你可以通过它阻止 Algolia 抓取某些 URL
      ],
      discoveryPatterns: [
      // 这是 Algolia 抓取 URL 的范围
      "https://YOUR_WEBSITE_URL/**",
      ],
      // 爬虫执行的计划时间，可根据文档更新频率设置
      schedule: "at 02:00 every 1 day",
      actions: [
      // 你可以拥有多个 action，特别是你在一个域名下部署多个文档时
      {
      // 使用适当的名称为索引命名
      indexName: "YOUR_INDEX_NAME",
      // 索引生效的路径
      pathsToMatch: ["https://YOUR_WEBSITE_URL/**"],
      // 控制 Algolia 如何抓取你的站点
      recordExtractor: ({ $, helpers }) => {
      // 以下是适用于 vuepress-theme-hope 的默认选项选项
      return helpers.docsearch({
      recordProps: {
      lvl0: {
      selectors: [".vp-sidebar-link.active", "[vp-content] h1"],
      defaultValue: "Documentation",
      },
      lvl1: "[vp-content] h1",
      lvl2: "[vp-content] h2",
      lvl3: "[vp-content] h3",
      lvl4: "[vp-content] h4",
      lvl5: "[vp-content] h5",
      lvl6: "[vp-content] h6",
      content: "[vp-content] p, [vp-content] li",
      },
      recordVersion: "v3",
      });
      },
      },
      ],
      initialIndexSettings: {
      // 控制索引如何被初始化，这仅当索引尚未生成时有效
      // 你可能需要在修改后手动删除并重新生成新的索引
      YOUR_INDEX_NAME: {
      attributesForFaceting: ["type", "lang"],
      attributesToRetrieve: ["hierarchy", "content", "anchor", "url"],
      attributesToHighlight: ["hierarchy", "hierarchy_camel", "content"],
      attributesToSnippet: ["content:10"],
      camelCaseAttributes: ["hierarchy", "hierarchy_radio", "content"],
      searchableAttributes: [
      "unordered(hierarchy_radio_camel.lvl0)",
      "unordered(hierarchy_radio.lvl0)",
      "unordered(hierarchy_radio_camel.lvl1)",
      "unordered(hierarchy_radio.lvl1)",
      "unordered(hierarchy_radio_camel.lvl2)",
      "unordered(hierarchy_radio.lvl2)",
      "unordered(hierarchy_radio_camel.lvl3)",
      "unordered(hierarchy_radio.lvl3)",
      "unordered(hierarchy_radio_camel.lvl4)",
      "unordered(hierarchy_radio.lvl4)",
      "unordered(hierarchy_radio_camel.lvl5)",
      "unordered(hierarchy_radio.lvl5)",
      "unordered(hierarchy_radio_camel.lvl6)",
      "unordered(hierarchy_radio.lvl6)",
      "unordered(hierarchy_camel.lvl0)",
      "unordered(hierarchy.lvl0)",
      "unordered(hierarchy_camel.lvl1)",
      "unordered(hierarchy.lvl1)",
      "unordered(hierarchy_camel.lvl2)",
      "unordered(hierarchy.lvl2)",
      "unordered(hierarchy_camel.lvl3)",
      "unordered(hierarchy.lvl3)",
      "unordered(hierarchy_camel.lvl4)",
      "unordered(hierarchy.lvl4)",
      "unordered(hierarchy_camel.lvl5)",
      "unordered(hierarchy.lvl5)",
      "unordered(hierarchy_camel.lvl6)",
      "unordered(hierarchy.lvl6)",
      "content",
      ],
      distinct: true,
      attributeForDistinct: "url",
      customRanking: [
      "desc(weight.pageRank)",
      "desc(weight.level)",
      "asc(weight.position)",
      ],
      ranking: [
      "words",
      "filters",
      "typo",
      "attribute",
      "proximity",
      "exact",
      "custom",
      ],
      highlightPreTag:
      '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: "</span>",
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      allowTyposOnNumericTokens: false,
      minProximity: 1,
      ignorePlurals: true,
      advancedSyntax: true,
      attributeCriteriaComputedByMinProximity: true,
      removeWordsIfNoResults: "allOptional",
      },
      },
  });

在项目中配置插件

在项目的theme.ts中添加插件配置：

export default hopeTheme({
    plugins: {
        //...
        docsearch : {
          appId: "xxx",
          apiKey: "xxx",
          indexName: "xxx"
        },
        //...
      }
})

然后就可以使用了