Docusaurus

github workflow configuration

deploy script

refers article

besides: you need install yarn and run yarn install in your docs project

Docusaurus Deployment

deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 22.19.0
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn build

      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.ACCESS_TOKEN }}
          # Build output to publish to the `gh-pages` branch:
          publish_dir: ./build
          # The following lines assign commit authorship to the official
          # GH-Actions bot for deploys to `gh-pages` branch:
          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
          # The GH actions bot is used by default if you didn't specify the two fields.
          # You can swap them out with your own user credentials.

configuration secrets

新版页面最小化权限配置TOKEN

分类	权限项	访问级别
🧱 Contents	Read and write	✅ 必需：允许 Action 推送 gh-pages 分支
⚙️ Actions	Read and write	✅ 可选：如果你的 Workflow 需要触发其他 Actions（例如 re-run workflows）

deploy error css net::ERR_ABORTED 404 (Not Found)

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  base: "/tenzies/", // 👈 your repo name here
});

DocSearch v2 not working in my site

Background

My Docusaurus(version 3.1.0) blog deploy on GitHub Page, before I change my domain from

https://halcyon666.github.io/summary/ to https://halcyon666.top, the DocSearch v2 works in my site. When I apply the

DocSearch again for my new domain, I just do the same as before doing, the search doesn't work.

The URL Ignorance

Firstly I checked the crawler admin https://crawler.algolia.com/, I found many website url be ignore, because there are many 302 redirection in my new application.

I try search in the Preview Search, There is not a result about my markdown blogs except homepage informations.

you can see my correct configuration above, and the wrong configuration below, in this case solve the scrawler ignore problems.

new Crawler({
  sitemaps: [],
  ignoreCanonicalTo: false,
});

In this time I can search in the Search Preview, but not in my site.

The Invalid Application-ID or API key

resolve Invalid Application-ID or API key, I check the helpful url, and find my API Key is wrong, given by the DocSearch rely email, so when you encounter this error, you need check your API key in your dashboard

The misunderstand faceFilters

Has result in Preview Search , but not in my site.

I get both payload from Preview Search and my site, I compare those parameters, and find that there some different with my parameters.So I checked the docusaurus docs, and fix this by changing the configuration.

This is the wrong payload Parameter in the end of the request url.

facetFilters=["language:zh",["docusaurus_tag:default","docusaurus_tag:docs-default-current"]]

and my wrong configuration is

contextualSearch: true,
searchParameters: {},

You need to indicate the contextualSearch to false(hint: this configuration in docusaurus.config.ts or docusaurus.config.js), and write you language filter to in brackets. You can see my fixed example below.

contextualSearch: false,
searchParameters: {
  // maybe yours is en
	facetFilters: ["zh"],
},

React Live 在 Docusaurus中使用时失效的问题

成功和失效时效果对比

失效场景图

正常场景图

造成失效提交Commit记录

添加组件TailProtocal

修复方案

单独导入组件，不使用全局导入。

修复commit记录

协议

本作品代码部分采用 Apache 2.0协议 进行许可。遵循许可的前提下，你可以自由地对代码进行修改，再发布，可以将代码用作商业用途。但要求你：

• 署名：在原有代码和衍生代码中，保留原作者署名及代码来源信息。
• 保留许可证：在原有代码和衍生代码中，保留Apache 2.0协议文件。

本作品文档部分采用 知识共享署名 4.0 国际许可协议 进行许可。遵循许可的前提下，你可以自由地共享，包括在任何媒介上以任何形式复制、发行本作品，亦可以自由地演绎、修改、转换或以本作品为基础进行二次创作。但要求你：

• 署名：应在使用本文档的全部或部分内容时候，注明原作者及来源信息。
• 非商业性使用：不得用于商业出版或其他任何带有商业性质的行为。如需商业使用，请联系作者。
• 相同方式共享的条件：在本文档基础上演绎、修改的作品，应当继续以知识共享署名 4.0国际许可协议进行许可。