Chuyaoyuan/code-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Chuyaoyuan
2026-04-29 19:03:25 +08:00
parent dd96d763b6
commit da65b3e73d
27 changed files with 471 additions and 25318 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/deploy.yml
+57
View File
@@ -0,0 +1,57 @@
name: Deploy to Production
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
env:
ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
- name: Upload build artifact
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
uses: actions/upload-artifact@v4
with:
name: build
path: build/
retention-days: 1
deploy:
name: Deploy
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
- name: Download build artifact
uses: actions/download-artifact@v4
with:
name: build
path: build/
- name: Deploy via FTP
uses: SamKirkland/FTP-Deploy-Action@v4.3.5
with:
server: ${{ secrets.FTP_SERVER }}
username: ${{ secrets.FTP_USER }}
password: ${{ secrets.FTP_PWD }}
local-dir: ./build/
server-dir: code-docs/www/
.github/workflows/nodejs.yml
-28
View File
@@ -1,28 +0,0 @@
on: push
name: 🚀 Deploy website on push
jobs:
web-deploy:
name: 🎉 Deploy
runs-on: ubuntu-latest
steps:
- name: 🚚 Get latest code
uses: actions/checkout@v2.3.2
- name: Use Node.js 12
uses: actions/setup-node@v2-beta
with:
node-version: '12'
- name: 🔨 Build Project
run: |
npm install
npm run build
- name: 📂 Sync files
uses: SamKirkland/FTP-Deploy-Action@4.0.0
with:
server: ${{ secrets.ftp_server }}
username: ${{ secrets.ftp_user }}
password: ${{ secrets.ftp_pwd }}
local-dir: ./build/
server-dir: code-docs/www/
.gitignore
+7
View File
@@ -108,3 +108,10 @@ dist
build
.idea
# macOS
.DS_Store
# Environment variables (never commit secrets)
.env.local
.env.*.local
babel.config.js → babel.config.ts
+1 -1
View File
@@ -1,3 +1,3 @@
module.exports = {
export default {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
blog/2021-01-01-hello-world.md
-18
View File
@@ -1,18 +0,0 @@
---
slug: hello-world
title: Hello Welcome
author: Endilie Yacop Sucipto
author_title: Maintainer of Docusaurus
author_url: https://github.com/endiliey
author_image_url: https://s3.ax1x.com/2021/02/26/6SEr4g.jpg
tags: [hello, chuyaoyuan]
---
Welcome to this blog. This blog is created .
欢迎来到这个博客。此博客已创建
<!--truncate-->
This is a test post.
A whole bunch of other information.
blog/2021-01-01-hola.md
-11
View File
@@ -1,11 +0,0 @@
---
slug: join in
title: 加入到这里
author: yaoyuan chu
author_title: chuyaoyuan
author_url: https://github.com/chuyaoyuan
author_image_url: https://s3.ax1x.com/2021/02/26/6SEr4g.jpg
tags: [hola, code-docs]
---
这里是个公开的技术文档聚集之地，可以随时随地的发表新文档，GitHub：[**code-docs**](https://github.com/chuyaoyuan/code-docs).
docs/tutorial-basics/_category_.json
-4
View File
@@ -1,4 +0,0 @@
{
"label": "文档教程 - 基础",
"position": 14
}
docs/tutorial-basics/congratulations.md
-21
View File
@@ -1,21 +0,0 @@
---
sidebar_position: 6
---
# Congratulations!
You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
Docusaurus has **much more to offer**!
Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
## What's next?
- Read the [official documentation](https://docusaurus.io/).
- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
- Add a [search bar](https://docusaurus.io/docs/search)
- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)
docs/tutorial-basics/create-a-blog-post.md
-29
View File
@@ -1,29 +0,0 @@
---
sidebar_position: 3
---
# Create a Blog Post
Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
## Create your first Post
Create a file at `blog/2021-02-28-greetings.md`:
```md title="blog/2021-02-28-greetings.md"
---
slug: greetings
title: Greetings!
author: Steven Hansel
author_title: Docusaurus Contributor
author_url: https://github.com/ShinteiMai
author_image_url: https://github.com/ShinteiMai.png
tags: [greetings]
---
Congratulations, you have made your first post!
Feel free to play around and edit this post as much you like.
```
A new blog post is now available at `http://localhost:3000/blog/greetings`.
docs/tutorial-basics/create-a-document.md
-56
View File
@@ -1,56 +0,0 @@
---
sidebar_position: 2
---
# Create a Document
Documents are **groups of pages** connected through:
- a **sidebar**
- **previous/next navigation**
- **versioning**
## Create your first Doc
Create a markdown file at `docs/hello.md`:
```md title="docs/hello.md"
# Hello
This is my **first Docusaurus document**!
```
A new document is now available at `http://localhost:3000/docs/hello`.
## Configure the Sidebar
Docusaurus automatically **creates a sidebar** from the `docs` folder.
Add metadatas to customize the sidebar label and position:
```diff title="docs/hello.md"
+ ---
+ sidebar_label: "Hi!"
+ sidebar_position: 3
+ ---
# Hello
This is my **first Docusaurus document**!
```
It is also possible to create your sidebar explicitly in `sidebars.js`:
```diff title="sidebars.js"
module.exports = {
tutorialSidebar: [
{
type: 'category',
label: 'Tutorial',
- items: [...],
+ items: ['hello'],
},
],
};
```
docs/tutorial-basics/create-a-page.md
-43
View File
@@ -1,43 +0,0 @@
---
sidebar_position: 1
---
# Create a Page
Add **Markdown or React** files to `src/pages` to create a **standalone page**:
- `src/pages/index.js` -> `localhost:3000/`
- `src/pages/foo.md` -> `localhost:3000/foo`
- `src/pages/foo/bar.js` -> `localhost:3000/foo/bar`
## Create your first React Page
Create a file at `src/pages/my-react-page.js`:
```jsx title="src/pages/my-react-page.js"
import React from 'react';
import Layout from '@theme/Layout';
export default function MyReactPage() {
return (
<Layout>
<h1>My React page</h1>
<p>This is a React page</p>
</Layout>
);
}
```
A new page is now available at `http://localhost:3000/my-react-page`.
## Create your first Markdown Page
Create a file at `src/pages/my-markdown-page.md`:
```mdx title="src/pages/my-markdown-page.md"
# My Markdown page
This is a Markdown page
```
A new page is now available at `http://localhost:3000/my-markdown-page`.
docs/tutorial-basics/deploy-your-site.md
-31
View File
@@ -1,31 +0,0 @@
---
sidebar_position: 5
---
# Deploy your site
Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
It builds your site as simple **static HTML, JavaScript and CSS files**.
## Build your site
Build your site **for production**:
```bash
npm run build
```
The static files are generated in the `build` folder.
## Deploy your site
Test your production build locally:
```bash
npm run serve
```
The `build` folder is now served at `http://localhost:3000/`.
You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).
docs/tutorial-basics/markdown-features.mdx
-144
View File
@@ -1,144 +0,0 @@
---
sidebar_position: 4
---
# Markdown Features
Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
## Front Matter
Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
```text title="my-doc.md"
// highlight-start
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---
// highlight-end
## Markdown heading
Markdown text with [links](./hello.md)
```
## Links
Regular Markdown links are supported, using url paths or relative file paths.
```md
Let's see how to [Create a page](/create-a-page).
```
```md
Let's see how to [Create a page](./create-a-page.md).
```
**Result:** Let's see how to [Create a page](./create-a-page.md).
## Images
Regular Markdown images are supported.
Add an image at `static/img/docusaurus.png` and display it in Markdown:
```md
![Docusaurus logo](/img/docusaurus.png)
```
![Docusaurus logo](/img/docusaurus.png)
## Code Blocks
Markdown code blocks are supported with Syntax highlighting.
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
return (
<h1>Hello, Docusaurus!</h1>
)
}
```
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}
```
## Admonitions
Docusaurus has a special syntax to create admonitions and callouts:
:::tip My tip
Use this awesome feature option
:::
:::danger Take care
This action is dangerous
:::
:::tip My tip
Use this awesome feature option
:::
:::danger Take care
This action is dangerous
:::
## MDX and React Components
[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
```jsx
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
</span>
);
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
```
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`);
}}>
{children}
</span>
);
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
docs/tutorial-extras/_category_.json
-4
View File
@@ -1,4 +0,0 @@
{
"label": "文档教程 - 高级",
"position": 15
}
docs/tutorial-extras/manage-docs-versions.md
-55
View File
@@ -1,55 +0,0 @@
---
sidebar_position: 1
---
# Manage Docs Versions
Docusaurus can manage multiple versions of your docs.
## Create a docs version
Release a version 1.0 of your project:
```bash
npm run docusaurus docs:version 1.0
```
The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
Your docs now have 2 versions:
- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
## Add a Version Dropdown
To navigate seamlessly across versions, add a version dropdown.
Modify the `docusaurus.config.js` file:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'docsVersionDropdown',
},
// highlight-end
],
},
},
};
```
The docs version dropdown appears in your navbar:
![Docs Version Dropdown](/img/tutorial/docsVersionDropdown.png)
## Update an existing version
It is possible to edit versioned docs in their respective folder:
- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`
docs/tutorial-extras/translate-your-site.md
-88
View File
@@ -1,88 +0,0 @@
---
sidebar_position: 2
---
# Translate your site
Let's translate `docs/getting-started.md` to French.
## Configure i18n
Modify `docusaurus.config.js` to add support for the `fr` locale:
```js title="docusaurus.config.js"
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
};
```
## Translate a doc
Copy the `docs/getting-started.md` file to the `i18n/fr` folder:
```bash
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
cp docs/getting-started.md i18n/fr/docusaurus-plugin-content-docs/current/getting-started.md
```
Translate `i18n/fr/docusaurus-plugin-content-docs/current/getting-started.md` in French.
## Start your localized site
Start your site on the French locale:
```bash
npm run start -- --locale fr
```
Your localized site is accessible at `http://localhost:3000/fr/` and the `Getting Started` page is translated.
:::caution
In development, you can only use one locale at a same time.
:::
## Add a Locale Dropdown
To navigate seamlessly across languages, add a locale dropdown.
Modify the `docusaurus.config.js` file:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'localeDropdown',
},
// highlight-end
],
},
},
};
```
The locale dropdown now appears in your navbar:
![Locale Dropdown](/img/tutorial/localeDropdown.png)
## Build your localized site
Build your site for a specific locale:
```bash
npm run build -- --locale fr
```
Or build your site to include all the locales at once:
```bash
npm run build
```
docusaurus.config.js → docusaurus.config.ts
+38 -35
View File
@@ -1,8 +1,9 @@
/** @type {import('@docusaurus/types').DocusaurusConfig} */
const math = require('remark-math');
const katex = require('rehype-katex');
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
module.exports = {
const config: Config = {
title: 'CodeDocs 编程文档',
tagline: 'CodeDocs 编程文档 -- 这里是一些技术人的编程文档',
url: 'http://docs.yaoyuan.io/',
@@ -10,23 +11,33 @@ module.exports = {
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
organizationName: 'chuyaoyuan', // Usually your GitHub org/user name.
projectName: 'code-docs', // Usually your repo name.
organizationName: 'chuyaoyuan',
projectName: 'code-docs',
i18n: {
defaultLocale: 'zh-cn',
locales: ['zh-cn', 'en'],
localeConfigs: {
'zh-cn': {
label: '中文',
direction: 'ltr',
htmlLang: 'zh-CN',
},
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
},
},
},
themeConfig: {
algolia: {
apiKey: '204335ce5ba2700fd04046b290498627',
apiKey: process.env.ALGOLIA_API_KEY ?? '',
appId: process.env.ALGOLIA_APP_ID ?? '',
indexName: 'code-docs',
// Optional: see doc section below
contextualSearch: true,
// Optional: see doc section below
appId: 'D8PEAPGLZ3',
// Optional: Algolia search parameters
searchParameters: {},
//... other Algolia params
},
navbar: {
title: 'CodeDocs 编程文档',
@@ -43,12 +54,12 @@ module.exports = {
},
{ to: '/blog', label: 'Blog', position: 'left' },
{
type: 'localeDropdown',
href: 'https://github.com/chuyaoyuan/code-docs',
label: 'GitHub',
position: 'right',
},
{
href: 'https://github.com/chuyaoyuan/code-docs',
label: 'GitHub',
type: 'localeDropdown',
position: 'right',
},
],
@@ -76,10 +87,6 @@ module.exports = {
label: 'Discord',
href: 'https://discordapp.com/',
},
{
label: 'Twitter',
href: 'https://twitter.com/',
},
],
},
{
@@ -111,38 +118,34 @@ module.exports = {
],
copyright: `Copyright © ${new Date().getFullYear()} Code Docs, Inc. 一些技术人的编程文档网站.`,
},
},
} satisfies Preset.ThemeConfig,
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css',
href: 'https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X',
crossorigin: 'anonymous',
},
],
presets: [
[
'@docusaurus/preset-classic',
'classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// Please change this to your repo.
remarkPlugins: [math],
rehypePlugins: [katex],
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/',
sidebarPath: './sidebars.ts',
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
},
blog: {
showReadingTime: true,
// Please change this to your repo.
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/blog/',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
customCss: './src/css/custom.css',
},
} satisfies Preset.Options,
],
],
};
export default config;
jilu.md
+279
View File
@@ -0,0 +1,279 @@
Read [](file:///opt/cyy/code-docs)
Read [](file:///opt/cyy/code-docs/package.json)
Read [](file:///opt/cyy/code-docs/docusaurus.config.js#1-1), lines 1 to 120
Read [](file:///opt/cyy/code-docs/sidebars.js)
Read [](file:///opt/cyy/code-docs/src/components/HomepageFeatures.js#1-1), lines 1 to 50
Read [](file:///opt/cyy/code-docs/src/pages/index.js)
Read [](file:///opt/cyy/code-docs/babel.config.js)
Read [](file:///opt/cyy/code-docs/.github)
Read [](file:///opt/cyy/code-docs/docs/intro-docs.md#1-1), lines 1 to 40
Read [](file:///opt/cyy/code-docs/.github/workflows)
Read [](file:///opt/cyy/code-docs/docs/LeetCode/CodingInterviews/StackAndQueue/MaxValueOfQueue.md#1-1), lines 1 to 50
Read [](file:///opt/cyy/code-docs/.github/workflows/nodejs.yml)
Read [](file:///opt/cyy/code-docs/docs/LeetCode/CodingInterviews/StackAndQueue/%E4%BA%8C%E5%8F%89%E6%A0%91%E7%9A%84%E9%81%8D%E5%8E%86.md#1-1), lines 1 to 30
Let me check for the garbled files:
Ran terminal command: find /opt/cyy/code-docs -maxdepth 1 -type f | sort && echo "---" && ls -la /opt/cyy/code-docs/ | head -30
Found them. Both are empty files (size 0) with garbled names. Let me delete them:
Ran terminal command: cd /opt/cyy/code-docs && find . -maxdepth 1 -name "2p" -delete && find . -maxdepth 1 -name $',\xef\xbf\xbd0p>*' -delete 2>/dev/null; find . -maxdepth 1 -type f -size 0 ! -name ".*" | head -20
Ran terminal command: cd /opt/cyy/code-docs && ls -la | grep "^-rw.* 0 " | awk '{print $NF}' && find . -maxdepth 1 -type f -size 0 -exec rm -v {} \;
Ran terminal command: cd /opt/cyy/code-docs && find . -maxdepth 1 -type f -size 0 | wc -l && ls | head -20
Both garbled files removed. Now let me read the remaining docs for the full analysis:
Read [](file:///opt/cyy/code-docs/blog/2021-04-26-use-code-docs.md)
Read [](file:///opt/cyy/code-docs/src/css/custom.css)
Now I have a complete picture. Let me compose the professional analysis and upgrade prompt:
---
## 两个乱码文件处理完毕
已删除根目录下的两个空白乱码文件：
- `2p`（空文件）
- `,°0p>;°8p>...Rich2p>PEd...`（空文件，名称为二进制乱码）
---
## 项目分析报告 + 系统升级提示词
---
## 一、项目现状分析
| 维度 | 当前状态 | 风险等级 |
|------|----------|----------|
| Docusaurus 版本 | `2.0.0-alpha.73` (2021年) | 🔴 极高 |
| React 版本 | `17.0.1` | 🟠 高 |
| Node.js (CI) | `12` (EOL) | 🔴 极高 |
| 部署方式 | FTP 明文传输 | 🔴 安全风险 |
| Algolia Key | 硬编码在公开配置文件 | 🔴 信息泄露 |
| TypeScript | 未使用 | 🟡 中 |
| 包管理器 | yarn.lock + package-lock.json 混用 | 🟠 高 |
---
## 二、问题点清单
**严重问题：**
1. `@docusaurus/core: 2.0.0-alpha.73` — 当前稳定版为 `3.7.x`，跨越近3年迭代，含大量Breaking Changes
2. Node.js 12 已于2022年4月正式 EOL，CI/CD 中仍在使用
3. Algolia `apiKey` 明文暴露在 docusaurus.config.js
4. `remark-math@3` + `rehype-katex@4` 与 Docusaurus 3.x 使用的 MDX 3.x 不兼容
5. .DS_Store 文件未被 .gitignore 过滤，已提交到仓库
**架构问题：**
6. 纯 JavaScript 项目，Docusaurus 3.x 全面支持 TypeScript，缺失类型安全
7. FTP 部署方案无加密、无回滚、无原子发布能力
8. GitHub Actions 使用过期版本：`actions/checkout@v2.3.2`、`actions/setup-node@v2-beta`
9. yarn.lock 和 package-lock.json 同时存在，包管理器冲突
10. CI 无分支过滤，每次 push（包括草稿分支）都会触发生产部署
**内容问题：**
11. HomepageFeatures.js 仍为 Docusaurus 默认英文占位内容
12. 依赖外部图片 CDN（`s3.ax1x.com`、`z3.ax1x.com`）存在链接失效风险
13. i18n 配置了 `en`/`zh-cn` 双语，但无对应翻译文件
14. Blog 文章内含硬编码域名链接 `http://docs.yaoyuan.io/...`
15. Tutorial 目录仍为 Docusaurus 官方示例内容，未替换为项目自有文档
---
## 三、系统升级提示词（可直接用于 AI 对话）
```
你是一名资深全栈工程师，精通 Docusaurus、React、GitHub Actions 和技术文档工程。
我需要你对下述项目进行全面系统升级，请严格按照优先级顺序执行，给出完整可执行的代码和配置。
## 项目背景
- 项目名称：code-docs（CodeDocs 编程文档站）
- 当前框架：Docusaurus v2.0.0-alpha.73（React 17，纯 JS）
- 内容：中文技术文档，包含 LeetCode、Spring Boot、Spring Cloud、React、Vue 专题
- 部署：GitHub Actions → FTP → 自托管服务器（http://docs.yaoyuan.io）
---
## 升级任务列表（按优先级排序）
### P0 - 核心框架升级
**1. 升级 Docusaurus 3.x**
- 将 `@docusaurus/core` 和 `@docusaurus/preset-classic` 从 `2.0.0-alpha.73` 升级到最新稳定版 `^3.7.0`
- 同步升级所有 peer dependencies：`react@^18.3`、`react-dom@^18.3`
- 迁移 `docusaurus.config.js` 为 `docusaurus.config.ts`（TypeScript 配置）
- 替换已废弃 API：
- `module.exports` → `export default` (ESM)
- `DocusaurusConfig` 类型导入路径变更
- `themeConfig.algolia` 结构校验更新
- 更新 MDX 依赖以兼容 MDX 3.x：
- `remark-math` 升级到 `^6.0`，`rehype-katex` 升级到 `^7.0`
- 检查所有使用 MDX JSX 语法的 `.md` 文件（如 `docs/intro-docs.md` 中的 `<Tabs>`），确保兼容 MDX 3 严格模式
**2. 升级 TypeScript 支持**
- 初始化 `tsconfig.json`（继承 `@docusaurus/tsconfig`）
- 将 `src/` 目录下所有 `.js`/`.jsx` 文件迁移为 `.ts`/`.tsx`
- 为 `HomepageFeatures`、`index` 页面添加完整 Props 类型声明
- 升级 `babel.config.js` → `babel.config.ts`
---
### P1 - 安全修复
**3. 消除 Algolia Key 泄露风险**
- 将 `docusaurus.config` 中硬编码的 Algolia `apiKey`、`appId` 提取到环境变量
- 创建 `.env.local` 文件（加入 `.gitignore`）：
```
ALGOLIA_APP_ID=D8PEAPGLZ3
ALGOLIA_API_KEY=<your_search_only_api_key>
```
- 在配置中使用 `process.env.ALGOLIA_APP_ID` 引用
- 在 GitHub Actions 中添加对应 `secrets`
**4. 修复 `.gitignore`**
添加以下条目：
```
.DS_Store
.env.local
.env.*.local
```
---
### P2 - CI/CD 现代化
**5. 重写 GitHub Actions 工作流**
```yaml
# .github/workflows/deploy.yml
name: Deploy to Production
on:
push:
branches: [main] # 仅 main 分支触发，移除草稿分支误部署
pull_request:
branches: [main] # PR 仅做构建校验，不部署
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4 # 升级到 v4
- uses: actions/setup-node@v4 # 升级到 v4
with:
node-version: '20' # Node 20 LTS
cache: 'npm' # 启用依赖缓存
- name: Install dependencies
run: npm ci # 使用 ci 替代 install，更稳定
- name: Build
run: npm run build
env:
ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
deploy:
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
# 推荐迁移至 GitHub Pages 或 SSH 部署，若保留 FTP 则升级：
- uses: SamKirkland/FTP-Deploy-Action@v4.3.5
with:
server: ${{ secrets.FTP_SERVER }}
username: ${{ secrets.FTP_USER }}
password: ${{ secrets.FTP_PWD }}
local-dir: ./build/
server-dir: code-docs/www/
```
> **架构建议**：将 FTP 部署迁移至 GitHub Pages（零成本）或 Vercel（自动预览 PR），消除明文传输风险。
---
### P3 - 内容与架构优化
**6. 首页本地化改造**
将 `src/components/HomepageFeatures.tsx` 的英文占位内容替换为项目实际特性：
```tsx
const FeatureList: FeatureItem[] = [
{
title: '📚 系统化文档',
description: '涵盖后端（Spring Boot/Cloud）、前端（React/Vue）和算法（LeetCode），分门别类，清晰索引。',
},
{
title: '⚡ 快速检索',
description: '集成 Algolia DocSearch，毫秒级全文检索，快速定位任意知识点。',
},
{
title: '🌐 持续更新',
description: '由技术团队持续维护，定期同步最新技术栈实践和面试题解析。',
},
];
```
移除对 `undraw_docusaurus_*.svg` 的依赖（这些文件在 img 中可能不存在）。
**7. 清理默认内容**
- 删除 tutorial-basics 和 tutorial-extras 目录（Docusaurus 默认示例，与项目无关）
- 删除 2021-01-01-hello-world.md 和 2021-01-01-hola.md（官方示例博客）
- 统一 Blog 文章中的链接为相对路径，移除硬编码域名
**8. 图片资源本地化**
将外部 CDN 图片（`s3.ax1x.com`、`z3.ax1x.com`）下载到 img 目录，
替换为相对路径引用，避免 CDN 失效导致图片断链。
**9. 统一包管理器**
删除 package-lock.json（保留 yarn.lock），或删除 yarn.lock（保留 `npm`），
在 package.json 中声明 `"packageManager": "npm@10.x.x"` 或 `"yarn@4.x.x"` 固定版本。
**10. 完善 i18n（可选）**
当前 `docusaurus.config` 配置了 `zh-cn` + `en` 双语，但缺少翻译文件。
执行 `npm run write-translations` 生成翻译模板，或移除 `en` locale 以减少维护成本。
---
## 升级注意事项
1. **Breaking Change 重点**：Docusaurus 3.x 使用 MDX 3，对 `{}` 中的 HTML 实体、未闭合标签更严格，升级后需逐一检测现有 `.md`/`.mdx` 文件：
```bash
npx docusaurus-mdx-checker
```
2. **KaTeX 配置变更**：`remark-math` v6+ 和 `rehype-katex` v7+ 的引入方式从 `require()` 改为 ES Module `import`，`docusaurus.config.ts` 需同步调整
3. **React 18 并发模式**：`ReactDOM.render` 已废弃，检查是否有自定义入口文件使用旧 API
4. **升级顺序建议**：
```
Step 1: 先在新分支 feat/upgrade-v3 上操作
Step 2: 升级依赖 → Step 3: 修复 MDX 兼容性 → Step 4: 本地构建验证
Step 5: 修复 CI/CD → Step 6: 合并到 main 触发部署
```
---
## 升级后验证清单
- [ ] `npm run build` 零报错、零警告
- [ ] `npm run start` 本地预览正常
- [ ] 中文搜索正常（Algolia）
- [ ] KaTeX 数学公式正常渲染
- [ ] 深色模式外观正常
- [ ] GitHub Actions 仅 `main` 分支触发部署
- [ ] 无硬编码密钥在代码仓库中
package-lock.json
Generated
-14843
View File
File diff suppressed because it is too large Load Diff
package.json
+15 -9
View File
@@ -2,6 +2,7 @@
"name": "code-docs",
"version": "0.0.0",
"private": true,
"packageManager": "npm@10.9.2",
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
@@ -11,17 +12,22 @@
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
"write-heading-ids": "docusaurus write-heading-ids",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.73",
"@docusaurus/preset-classic": "2.0.0-alpha.73",
"@mdx-js/react": "^1.6.21",
"clsx": "^1.1.1",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"rehype-katex": "^4.0.0",
"remark-math": "^3.0.1"
"@docusaurus/core": "^3.7.0",
"@docusaurus/preset-classic": "^3.7.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.1.1",
"react": "^18.3.1",
"react-dom": "^18.3.1",
"rehype-katex": "^7.0.0",
"remark-math": "^6.0.0"
},
"devDependencies": {
"@docusaurus/tsconfig": "^3.7.0",
"typescript": "^5.4.5"
},
"browserslist": {
"production": [
sidebars.js
-26
View File
@@ -1,26 +0,0 @@
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/
module.exports = {
// By default, Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
// But you can create a sidebar manually
/*
tutorialSidebar: [
{
type: 'category',
label: 'Tutorial',
items: ['hello'],
},
],
*/
};
sidebars.ts
+8
View File
@@ -0,0 +1,8 @@
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
// Docusaurus auto-generates a sidebar from the docs folder structure
tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
};
export default sidebars;
src/components/HomepageFeatures.js
-64
View File
@@ -1,64 +0,0 @@
import React from 'react';
import clsx from 'clsx';
import styles from './HomepageFeatures.module.css';
const FeatureList = [
{
title: 'Easy to Use',
Svg: require('../../static/img/undraw_docusaurus_mountain.svg').default,
description: (
<>
Docusaurus was designed from the ground up to be easily installed and
used to get your website up and running quickly.
</>
),
},
{
title: 'Focus on What Matters',
Svg: require('../../static/img/undraw_docusaurus_tree.svg').default,
description: (
<>
Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
ahead and move your docs into the <code>docs</code> directory.
</>
),
},
{
title: 'Powered by React',
Svg: require('../../static/img/undraw_docusaurus_react.svg').default,
description: (
<>
Extend or customize your website layout by reusing React. Docusaurus can
be extended while reusing the same header and footer.
</>
),
},
];
function Feature({Svg, title, description}) {
return (
<div className={clsx('col col--4')}>
<div className="text--center">
<Svg className={styles.featureSvg} alt={title} />
</div>
<div className="text--center padding-horiz--md">
<h3>{title}</h3>
<p>{description}</p>
</div>
</div>
);
}
export default function HomepageFeatures() {
return (
<section className={styles.features}>
<div className="container">
<div className="row">
{FeatureList.map((props, idx) => (
<Feature key={idx} {...props} />
))}
</div>
</div>
</section>
);
}
src/components/HomepageFeatures.tsx
+51
View File
@@ -0,0 +1,51 @@
import React from 'react';
import clsx from 'clsx';
import styles from './HomepageFeatures.module.css';
interface FeatureItem {
title: string;
description: string;
}
const FeatureList: FeatureItem[] = [
{
title: '📚 系统化文档',
description:
'涵盖后端（Spring Boot/Cloud）、前端（React/Vue）和算法（LeetCode），分门别类，清晰索引。',
},
{
title: '⚡ 快速检索',
description:
'集成 Algolia DocSearch，毫秒级全文检索，快速定位任意知识点。',
},
{
title: '🌐 持续更新',
description:
'由技术团队持续维护，定期同步最新技术栈实践和面试题解析。',
},
];
function Feature({ title, description }: FeatureItem): JSX.Element {
return (
<div className={clsx('col col--4')}>
<div className="text--center padding-horiz--md">
<h3>{title}</h3>
<p>{description}</p>
</div>
</div>
);
}
export default function HomepageFeatures(): JSX.Element {
return (
<section className={styles.features}>
<div className="container">
<div className="row">
{FeatureList.map((props, idx) => (
<Feature key={idx} {...props} />
))}
</div>
</div>
</section>
);
}
src/pages/index.js → src/pages/index.tsx
+2 -2
View File
@@ -6,7 +6,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './index.module.css';
import HomepageFeatures from '../components/HomepageFeatures';
function HomepageHeader() {
function HomepageHeader(): JSX.Element {
const { siteConfig } = useDocusaurusContext();
return (
<header className={clsx('hero hero--primary', styles.heroBanner)}>
@@ -25,7 +25,7 @@ function HomepageHeader() {
);
}
export default function Home() {
export default function Home(): JSX.Element {
const { siteConfig } = useDocusaurusContext();
return (
<Layout
tsconfig.json
+6
View File
@@ -0,0 +1,6 @@
{
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
}
}
yarn.lock
-9799
View File
File diff suppressed because it is too large Load Diff