组件库项目开发文档库知识点1 | 青训营笔记

小柴Yaaaaa
167 阅读4分钟

这是我参与「第五届青训营」伴学笔记创作活动的第 18 天

1. Algolia 搜索功能

Algolia 是一个数据库实时搜索服务，能够提供毫秒级的数据库搜索服务，并且其服务能以 API 的形式方便地布局到网页、客户端、APP 等多种场景。

像 VuePress 官方文档就是使用的 Algolia 搜索，使用 Algolia 搜索最大的好处就是方便，它会自动爬取网站的页面内容并构建索引，你只用申请一个 Algolia 服务，在网站上添加一些代码，就像添加统计代码一样，然后就可以实现一个全文搜索功能

1）申请服务

搜索服务申请地址：docsearch.algolia.com/apply/

  1. 项目文档地址
  2. 邮箱
  3. 项目仓库地址

申请需要最少两天时间，有两个步骤：

  1. 等待 Algolia 审查项目，给你发邮件，然后需要你回复这个邮件说，你是这个项目的维护者
  2. 等待第二天通过审核会给你发来邮件，里面包含了 AppId 等所需要的信息邮件

image-20230203152122931

2）vitepress search 配置

将这些配置添加到 config.ts 文件内

image-20230203152953013

image-20230203152917103

3）参考文献

VuePress 博客优化之开启 Algolia 全文搜索 · Issue #267 · mqyqingfeng/Blog (github.com)

2. Github 自动部署并同步到 Gitee

在本地运行打包文档库项目后，自动在其 dist 位置，初始化 git init，然后将其代码推送到 github 的 pages 分支，在通过 actions 将打包项目同步打 gitee 然后更新项目文档

1）从 Gitee 同步 Github 仓库

打开 gitee 从 Github 导入自己的仓库

image-20230204164417028 image-20230204165831456

2）编写 sh 文件自动化执行代码

项目根目录创建 reploy.sh 文件

 #!/usr/bin/env sh
 ​
 # 确保脚本抛出遇到的错误
 set -e
 ​
 # 生成静态文件
 npm run docs:build
 ​
 # 进入生成的文件夹
 cd site/docs/.vitepress/dist
 ​
 git init
 git add -A
 git commit -m 'deploy'
 ​
 # 如果发布到 https://<USERNAME>.github.io/<REPO>
 git push -f git@github.com:mqyqingfeng/learn-typescript.git master:gh-pages
 ​
 cd -

运行这个文件 sh reploy.sh，不过这个文件，windows 没法运行，所以我们编写 gulp 命令来执行

项目根目录创建 script 文件夹，创建一个 utils 目录：

 // utils/index.ts
 import { spawn } from "child_process";
 ​
 // 用于执行 cmd 命令
 export default async (command: string, path: string) => {
   //cmd表示命令，args代表参数，如 rm -rf  rm就是命令，-rf就为参数
   const [cmd, ...args] = command.split(" ");
   return new Promise((resolve, reject) => {
     const app = spawn(cmd, args, {
       cwd: path, //执行命令的路径
       stdio: "inherit", //输出共享给父进程
       shell: true, //mac不需要开启，windows下git base需要开启支持
     });
     //执行完毕关闭并resolve
     app.on("close", resolve);
   });
 };

在新建一个 build 目录，创建 gulpfile.ts 和 index.ts 文件：

 // gulpfile.ts
 import { series } from "gulp";
 import { buildVitepressDist, pushGitHubPages } from "./index";
 ​
 export default series(
   () => buildVitepressDist(),
   () => pushGitHubPages(),
 );

 // index.ts
 import run from "../utils/run";
 import { root, viteDist } from "../utils/paths";
 ​
 const project = "hview-ui";
 const remote = "https://github.com/ChaiMayor/hview-ui.git";
 const branch = "gh-pages";
 ​
 // 构建文档库 dist
 export const buildVitepressDist = async () => {
   await run("pnpm run docs:build-other", root);
 };
 ​
 // 推送到 github pages 分支
 export const pushGitHubPages = async () => {
   await run("git init", viteDist);
   await run("git add .", viteDist);
   // 发布到 https://<USERNAME>.github.io/<REPO>
   await run(`git commit -m "deploy ${project} pages."`, viteDist);
   await run(`git remote add origin ${remote}`, viteDist);
   await run(`git checkout -b ${branch}`, viteDist);
   await run(`git push -u origin ${branch}`, viteDist);
 };

在根目录的 package.json 配置脚本命令：

 {
   "script": {
     "docs:build": "gulp -f script/build/gulpfile.ts"   // 用来执行脚本文件
   }
 }

3）同步 pages 代码到 gitee

A. 使用 https 方式添加（不配置公钥）

将刚才的代码稍加修改：

 const project = "hview-ui";
 const remoteGH = "https://github.com/ChaiMayor/hview-ui.git";
 const remoteGT = "https://gitee.com/chai-mayor/hview-ui.git";
 const branch = "gh-pages";
 ​
 // 推送到 github and gitee pages 分支
 export const pushGitHubPages = async () => {
   await run("git init", viteDist);
   await run("git add .", viteDist);
   // 发布到 https://<USERNAME>.github.io/<REPO>
   await run(`git commit -m "deploy ${project} pages."`, viteDist);
   await run(`git checkout -b ${branch}`, viteDist);
   await run(`git remote add origin ${remoteGH}`, viteDist);
   await run("git push -f origin gh-pages", viteDist);
   await run(`git remote add gitee ${remoteGT}`, viteDist);
   await run(`git push -f gitee ${branch}`, viteDist);
 };

B. 使用 ssh 方式添加（配置公钥）

配置公钥方法：2. Github 和 Gitee 配置公钥

文中教的配置 github 和 gitee 的公钥的文件

  1. .pub 这个是公钥文件
  2. 不带后缀的是私钥文件

image-20230205111123639

使用 SSH 推送代码：

 const project = "hview-ui";
 const sshGH = "git@github.com:ChaiMayor/hview-ui.git";
 const sshGT = "git@gitee.com:chai-mayor/hview-ui.git";
 const branch = "gh-pages";
 ​
 // 推送到 github and gitee pages 分支
 export const pushGitHubPages = async () => {
   await run("git init", viteDist);
   await run("git add .", viteDist);
   // 发布到 https://<USERNAME>.github.io/<REPO>
   await run(`git commit -m "deploy ${project} pages."`, viteDist);
   await run(`git push -f ${sshGH} master:${branch}`, viteDist);
   await run(`git push -f ${sshGT} master:${branch}`, viteDist);
 };

4）配置同步 Actions 代码

 # .github\workflows\updatePages.yml
 name: Sync
 on:
   push:
     branches: [gh-pages]
   workflow_dispatch:
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Sync to Gitee
         uses: wearerequired/git-mirror-action@master
         env:
           SSH_PRIVATE_KEY: ${{ secrets.GITEE_PRIVATE_KEY  }}
         with:
           source-repo: git@github.com:ChaiMayor/hview-ui.git
           destination-repo: git@gitee.com:chai-mayor/hview-ui.git
 ​
       - name: Build Gitee Pages
         uses: yanglbme/gitee-pages-action@main
         with:
           gitee-username: chai-mayor
           gitee-password: ${{ secrets.GITEE_PASSWORD }}
           gitee-repo: chai-mayor/hview-ui
           branch: gh-pages
           https: true

遇到错误：

  1. Error: Need captcha validation, please visit gitee.com/login, login to validate your account.

    • 微信关注 gitee 公众号绑定自己的 gitee 账号就行

  2. git@github.com: Permission denied (publickey).

    • secrets.GITEE_PRIVATE_KEY，这个要配置 id.ed25519 不带后缀的私钥才行，github 和 gitee 也都得配置 id.ed25519.pub 公钥才行

5）参考文献

一篇带你用 VuePress + Github Pages 搭建博客 · Issue #235 · mqyqingfeng/Blog

一篇教你代码同步 Github 和 Gitee · Issue #236 · mqyqingfeng/Blog

Gitee 如何自动部署 Pages？还是用 GitHub Actions!_慕课手记 (imooc.com)

Gitee Pages Action · Actions · GitHub Marketplace

avatar
文章
阅读
粉丝