升级

• 按文档修改package.json: https://docusaurus.nodejs.cn/docs/migration/v3
• 删除 package-lock.json
• 运行 yarn intall
• yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/theme-mermaid@latest @docusaurus/module-type-aliases@latest @docusaurus/types@latest @docusaurus/tsconfig@latest

部署

• 每次部署都会 clone 一次，非常的慢，需要设置 npm 和 yarn 的代理和 registry

  • 查看lanter的代理端口，设置为：yarn config set proxy 127.0.0.1:33137
  • 如果需要删除代理：yarn config delete proxy

• 使用这个命令进行部署：USE_SSH=true yarn deploy

• 注意在docusaurus.config.就是中指明了部署的分支是deploymentBranch: 'gh-pages'

  • 即在github上的分支
  • 在xxx.github.io/settings/pages中Branch设置为gh-pages，并设置Custom domain为: www.simpowater.org

CNAME

• 每次部署后, 都需要在settings/pages中重新设置Custom domain: www.simpowater.org

• 为了解决这个问题, 需要在static/文件夹下新建一个CNAME文件: www.simpowater.org

• facebook/docusaurus#3889

图片点击放大

• https://gabrielcsapo.github.io/docusaurus-plugin-image-zoom/docs/getting-started/
• npm install docusaurus-plugin-image-zoom --save

Mermaid

• 加入 mermaid https://docusaurus.io/zh-CN/docs/markdown-features/diagrams
  • yarn add @docusaurus/theme-mermaid@next # 通过 @ next 选择正确的版本 2.4.0
• mermaid in mdx: yarn add mdx-mermaid mermaid #

Algolia docsearch

• https://docusaurus.io/docs/search
• 申请后, 需要等待审核
• https://zhuanlan.zhihu.com/p/625637978

Github Action 自动在 push 后爬取

• https://oreo.life/en/blog/2023-02-12-crawl-website-using-github-actions/
  • https://crawler.algolia.com/admin/user/settings/ 获取Crawler User ID和Crawler API Key.
  • algolia-api-key用的是SEARCH_API_KEY
• .github/workflows/docsearch-scraper.yml:

name: Crawl

on:
  push:
    branches: [ "master" ]
  workflow_dispatch:

jobs:
  crawl:
    runs-on: ubuntu-latest
    steps:
      - name: Algolia Crawler Automatic Crawl
        uses: algolia/algoliasearch-crawler-github-actions@v1.1.10
        with:
          crawler-user-id: ${{ secrets.CRAWLER_USER_ID }}
          crawler-api-key: ${{ secrets.CRAWLER_API_KEY }}
          github-token: ${{ github.token }}
          crawler-name: 'simpowater'
          algolia-app-id: ${{ secrets.ALGOLIA_APP_ID }}
          algolia-api-key: ${{ secrets.ALGOLIA_SEARCH_API_KEY }}
          site-url: 'https://www.simpowater.org/docs'

• 注意: algoliasearch-crawler-github-actions版本升级：

  • 这里查询新版：https://github.com/algolia/algoliasearch-crawler-github-actions/releases

• 以下方式作废：

• 在根目录中添加docsearch-config.json: https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json

• 在根目录中.github/workflows/algolia-docsearch-scraper.yml

  • ALGOLIA_APP_ID和ALGOLIA_API_KEY在https://crawler.algolia.com后台获取
  • 具体内容见下:

# 以下 action 脚本作废
name: algolia-docsearch-scraper

on:
  push:
    branches: [master]


jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Sleep for 10 seconds
        run: sleep 10s
        shell: bash

      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Run scraper
        env:
          APPLICATION_ID: ${{ secrets.ALGOLIA_APP_ID }}
          API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
        run: |
          CONFIG="$(cat docsearch-config.json)"
          docker run -i --rm \
                  -e APPLICATION_ID=$APPLICATION_ID \
                  -e API_KEY=$API_KEY \
                  -e CONFIG="${CONFIG}" \
                  algolia/docsearch-scraper

问题：

• DocSearch Error: 400: Bad Request {"code":"invalid_action","message":"This action cannot be executed on a blocked crawler"}

  • https://support.algolia.com/hc/en-us/articles/12151775552017-DocSearch-Error-400-Bad-Request-code-invalid-action-message-This-action-cannot-be-executed-on-a-blocked-crawler#:~:text=When%20using%20the%20API%20of%20the%20Crawler%20and,and%20then%20the%20API%20will%20accept%20requests%20again.
  • When using the API of the Crawler and you find the Crawler is blocked, you can take a look at the frontend for more information: Crawler Admin Console
  • To fix the issue, you need to unblock the Crawler by clicking the Cancel button from the UI, and then the API will accept requests again.

  safetyChecks: { beforeIndexPublishing: { maxLostRecordsPercentage: 100 } },

  • Editor: safetyChecks: { beforeIndexPublishing: { maxLostRecordsPercentage: 100 } }

多语言

• https://docusaurus.io/docs/i18n/tutorial
• 生成翻译文档: yarn write-translations --locale zh
• 生成md:

  mkdir -p i18n/zh/docusaurus-plugin-content-docs/current
  cp -r docs/** i18n/zh/docusaurus-plugin-content-docs/current

• 启动语言服务器: yarn start --locale zh

强制删除某次github提交

• https://stackoverflow.com/questions/448919/how-can-i-remove-a-commit-on-github

# 获取某次提交的 hash
git log
# 删除这之前的提交
git reset --hard 71c27777543ccfcb0376dcdd8f6777df055ef479
# 强制推送一次
git push --force

---

Website

This website is built using Docusaurus 2, a modern static website generator.

Installation

$ yarn

Local Development

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

如果失败, 重新运行yarn install一次

Build

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

Using SSH:

$ USE_SSH=true yarn deploy

Not using SSH:

$ GIT_USER=<Your GitHub username> yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.