-
在首页点击「我要投稿」，或在任意文档右上角使用「编辑」/「我要投稿」按钮
-
因为编辑器自带了内卷地狱的图床供大家直接上传图片便捷使用，因此安全起见必须登录才能使用编辑器功能， 如果你已登录，则会直接进入，如果没登录则会进入以下页面
点sign in后，会跳转到github请求登录，登录后即可进入投稿页面。
首先投稿前需要填写稿件的基本信息：
标签将用于未来辅助人们用分类功能查看文章
然后下滑即可选择投稿目录：
浮窗中选择想贡献的章节，也可以先新建一个文件夹
然后就能进入编辑框开始写文档了
编辑器是类notion的设计，因此你可以选择文字来添加效果，
也可以直接使用markdown代码来编辑
# 标题1 ## 标题2
每点击一行，左边都有加号按钮，可以快捷添加你要的内容块
加号旁边的格子按钮则是可以拖拽文本块想要放置的位置，上拖下拖
值得一提的是编辑器的自带图床功能
你只需要粘贴图片到编辑器里，或是用自带的image代码块添加图片
，提交后，图片就会自动被上传到内卷地狱的图片，再也不需要自己手动配置图床手动上传了！
等你编辑完了以后，就可以点击底部按钮发布文章了。
-
页面会跳转到 GitHub
点击右上角的commit changes
-
点击
Commit changes，若是第一次投稿，GitHub 会提示先 Fork 仓库；按提示操作一次即可
-
Fork 完成后会自动返回原页面，然后一直“下一步”即可
再点击一次 Commit changes
随后进入 PR 流程，按提示一路继续
-
恭喜你完成了首次 Pull Request！ 🎉
—— 以下是代码贡献流程，若只提交文档可在此结束 ——
注意取消勾选仅克隆当前分支
git clone https://github.com/你自己的仓库名/involutionhell.git
修改为自己fork的仓库，改为你的https仓库的git地址
列出现有分支
git branch -a #用于列出当前Git仓库中所有的分支,包括本地分支和远程分支。
git checkout -b feat/your-feature
# 它的作用是创建一个新的分支并立即切换到该分支上。
具体来说，这个命令相当于同时执行了两个操作：
git branch feat/your-feature - 创建名为 feat/your-feature 的新分支
git checkout feat/your-feature - 切换到这个新创建的分支
其中 feat/your-feature 是分支名称，通常遵循约定式命名：
feat/ 前缀表示这是一个功能（feature）分支
后面的 your-feature 通常是对功能的简要描述
git checkout -b doc_raven # 自定义一个新的分支
#git checkout -b doc_id 分支名字改为你的uid分支名称
git add .
根据你的变动情况
git commit -m "add xxx" # 添加信息记录
or
git commit -m "edit xxx" # 修改信息记录
or
git commit -m "delete xxx" #删除信息记录
git push origin doc_raven
Windows + VSCode(Cursor) 用户：如遇 Husky 在 VSCode 内置终端阻止提交，请使用外部命令行执行
git commit。
本地离线调试 Fumadocs 时，如果发现界面加载需要等待远程图片尺寸请求，可以设置环境变量
DOCS_REMOTE_IMAGE_SIZE=disable或直接沿用默认行为（开发模式自动禁用远程图片尺寸请求），显著加快调试速度。如需强制启用远程图片尺寸补全，可手动设置DOCS_REMOTE_IMAGE_SIZE=force。
DOCS_REMOTE_IMAGE_SIZE |
行为说明 |
|---|---|
| 未设置（默认） | 构建时忽略远程图片尺寸请求报错，开发模式下额外禁用远程尺寸请求，避免离线调试受阻 |
disable |
在任何模式下都跳过远程图片尺寸请求，仅使用文档内手动声明的宽高 |
force |
强制启用远程图片尺寸请求，并在出现错误时抛出异常以暴露问题 |
原因：不同版本的 pnpm 使用不同的 YAML 序列化格式，即使依赖关系相同，锁文件的格式也可能不同。
解决方案：
-
确保使用正确的 pnpm 版本：
# 检查当前版本 pnpm --version # 应该显示: 10.20.0 # 如果不是，请使用以下命令之一： # 方法 1: 使用 corepack（推荐） corepack enable corepack prepare pnpm@10.20.0 --activate # 方法 2: 全局安装 npm install -g pnpm@10.20.0
-
验证版本一致性：
pnpm check:pnpm-version
-
如果 lockfile 已经被错误修改：
# 丢弃 lockfile 的修改 git checkout pnpm-lock.yaml # 确认使用正确的 pnpm 版本后重新安装 pnpm install
-
在提交前检查： 项目的 pre-commit hook 会自动检查 pnpm 版本和 lockfile 变更，如果发现版本不匹配会给出警告。
这通常意味着：
- 你本地使用的 pnpm 版本与项目要求的不一致
- lockfile 被错误修改或损坏
解决方案：
# 1. 确认并切换到正确的 pnpm 版本
corepack enable
pnpm --version # 确认是 10.20.0
# 2. 删除 node_modules 和重新安装
rm -rf node_modules
pnpm install
# 3. 检查 lockfile 是否有变更
git status
# 4. 如果没有变更，说明已修复；如果有变更，说明之前的 lockfile 确实有问题Corepack 的优势：
- 自动读取
package.json的packageManager字段 - 每个项目可以使用不同的 pnpm 版本而不冲突
- 新贡献者克隆项目后自动使用正确的版本
- 减少版本不匹配导致的问题
如何为团队启用 corepack：
# 一次性设置，之后所有项目都会受益
corepack enablegit clone https://github.com/involutionhell/involutionhell.git
cd involutionhell重要：为了避免 pnpm-lock.yaml 格式不一致的问题，请务必使用项目指定的 pnpm 版本！
本项目已在 package.json 中锁定了 pnpm 版本（"packageManager": "pnpm@10.20.0"），推荐使用 corepack 来自动管理正确的版本：
Corepack 是 Node.js 16.9+ 自带的工具，能自动使用 package.json 中指定的包管理器版本。
# 启用 corepack
corepack enable
# 安装依赖（corepack 会自动使用 pnpm@10.20.0）
pnpm install如果不想使用 corepack，可以手动安装项目指定的 pnpm 版本：
# 安装 pnpm 10.20.0
npm install -g pnpm@10.20.0
# 安装依赖
pnpm install安装完成后，请务必验证你使用的是正确的版本：
# 检查 pnpm 版本
pnpm --version
# 应该输出: 10.20.0
# 或使用项目提供的检查脚本
pnpm check:pnpm-version不同版本的 pnpm 在序列化 pnpm-lock.yaml 时可能使用不同的格式（如单引号 vs 双引号），导致：
- PR 中产生大量无意义的 diff
- 增加代码审查负担
- 可能导致 CI 检查失败
我们的 CI 工作流会自动检查版本一致性，如果检测到版本不匹配会导致构建失败。
运行开发服务器：
pnpm dev打开浏览器访问 http://localhost:3000。
修改 docs/ 下的 .md 文件，会自动热更新。
常用脚本集中在 package.json 中，以下是最常用的命令：
pnpm dev # 启动开发服务器
pnpm build # 构建生产版本
pnpm start # 启动生产服务器
pnpm lint:images # 检查图片是否符合规范
pnpm migrate:images # 自动迁移图片到对应 assets 目录
pnpm check:pnpm-version # 检查 pnpm 版本是否与 package.json 一致
pnpm check:lockfile # 检查 lockfile 是否有未预期的修改
pnpm postinstall # 同步必要的 Husky/Fumadocs 配置所有文档放在 docs/ 目录。
图片需要放在 被引用的文档的同名assets目录下(正常情况下您不应该关心这个, 该项目有自动脚本来移动图片), 例如:
docxA 引用了 imgA 图片, 那么他们的文档结构应该是 docxA.assets/imgA:
docsA.md
docsA.assets/
imgA
每个文档都需要一个 Frontmatter，例如：
---
title: Hello World
description: 简短描述
date: "2025-09-11"
tags:
- intro
---
# Hello World
这是正文内容。必填字段:
- title: 必填，文档标题
可选字段:
- description: 简短说明
- date: 发布日期
- tags: 标签列表
我们的文档采用分层式的 "Folder as a Book" 结构，会自动生成 URL 和导航。
📂 docs/
├── 📂 computer-science/ # 计算机科学
│ ├── 📄 index.md # 概述
│ └── 📂 data-structures/ # 数据结构
│ ├── 📄 index.md # 概述
│ ├── 📂 array/ # 数组
│ │ ├── 📄 index.md # 概述
│ │ ├── 📄 01-static-array.md # 静态数组
│ │ └── 📄 02-dynamic-array.md # 动态数组
│ └── 📂 linked-list/ # 链表
│ ├── 📄 index.md # 概述
│ └── 📄 01-singly-linked-list.md # 单向链表
文件结构会自动生成简洁的 URL：
docs/computer-science/index.md→/computer-sciencedocs/computer-science/data-structures/array/01-static-array.md→/computer-science/data-structures/array/static-array
文件夹:
- 使用
kebab-case命名:computer-science,data-structures - 每个主题文件夹应该有一个
index.md文件作为概述
文件:
- 使用
kebab-case命名:static-array.md - 使用数字前缀排序:
01-,02- - 前缀会自动从最终 URL 中移除
- 准确性：确保技术准确性
- 清晰性：编写清晰易懂的解释
- 完整性：全面覆盖主题
- 示例：包含实际代码示例
- 更新：保持内容更新
- 使用正确的标题层次结构 (h1 → h2 → h3)
- 包含带有语法高亮的代码块
- 使用表格进行比较
- 为图片添加替代文本
- 使用链接引用相关内容
// ✅ 好的做法：清晰、有注释的代码
function binarySearch(arr, target) {
let left = 0;
let right = arr.length - 1;
while (left <= right) {
const mid = Math.floor((left + right) / 2);
if (arr[mid] === target) {
return mid; // 找到目标
} else if (arr[mid] < target) {
left = mid + 1; // 搜索右半部分
} else {
right = mid - 1; // 搜索左半部分
}
}
return -1; // 未找到目标
}- 英文：使用清晰、专业的英文
- 中文：在需要时使用正式的学术中文
- 技术术语：使用标准技术术语
- 一致性：在整个文档中保持一致的术语
pnpm build这会在 .next 文件夹中创建优化的生产构建。
pnpm export导出后的 /out 目录包含静态站点，可直接部署到 GitHub Pages。
本仓库配置了 GitHub Actions，push 到 main 分支会自动构建并部署到：
无需手动操作。
- Fork 本仓库
- 为修改创建新分支
- 进行修改
- 测试修改
- 提交 PR
我们欢迎以下类型的贡献：
📝 内容贡献
- 修正文档内容
- 添加新的教程或指南
- 将内容翻译成其他语言
- 改进现有文章
🐛 错误修复
- 修复拼写和语法错误
- 修复损坏的链接
- 修复错误信息
- 改进代码示例
🎨 UI/UX 改进
- 改进页面样式
- 增强用户交互
- 改进移动端响应性
- 为 UI 添加新功能
优先使用 Fumadocs UI 组件库：
本项目已迁移到 Fumadocs UI 作为主要 UI 框架。请在进行 UI 相关开发时优先考虑：
-
使用 Fumadocs UI 组件：
- 查看 Fumadocs UI 文档 了解可用组件
- 优先使用内置组件而不是自定义实现
- 遵循 Fumadocs UI 的设计规范和样式指南
-
保持设计一致性：
- 使用统一的颜色方案和字体
- 遵循现有的组件样式和交互模式
- 保持响应式设计的兼容性
-
新功能开发：
- 在提 issue 讨论新功能需求时，请明确 UI 方面的具体要求
- 优先考虑使用 Fumadocs UI 的扩展功能
- 如需自定义组件，请与团队讨论以保持一致性
-
测试要求：
- 确保新 UI 功能在不同设备和屏幕尺寸下正常工作
- 测试主题切换（浅色/深色模式）兼容性
- 验证无障碍访问功能
🛠️ 技术改进
- 改进构建过程
- 添加新的脚本或工具
- 优化性能
- 改进可访问性
-
自动检查
- GitHub Actions 将运行自动化测试
- Fumadocs 将验证你的内容
- Linting 将检查代码质量
-
同行评审
- 至少一位维护者将审查你的 PR
- 审阅者可能会要求修改
- 你可以根据反馈更新你的 PR
-
合并
- 一旦批准，维护者将合并你的 PR
- 你的贡献将自动部署