Neoverse-Docs
参与共建

贡献指南

报告问题、改进内容或参与 Neoverse-Docs 开发

主要编写者：
ShenshijunShenshijun
本章 AI 摘要

你可以通过 Issue、文档修正、翻译或 Pull Request 参与 Neoverse-Docs。修改前先确认问题与范围，保持静态优先、Server-first、Fumadocs-first 和现有设计语言；修改后根据影响运行 bun lint、bun typecheck、Mermaid 资源生成或生产构建。bun check 会写入工作区，不应当作只读检查。

一、关于贡献

贡献不只意味着提交代码。以下改进都很有价值：

  • 报告事实错误、失效链接、无法复现的步骤或显示异常；
  • 改正文案、示例、图表、术语解释或学习路径；
  • 补充当前章节真正缺少的内容；
  • 修复可访问性、移动端、浅色 / 深色主题或性能问题；
  • 翻译已有内容，并保持术语与结构一致；
  • 参与代码审查，提供可验证的复现信息或替代方案。

如果改动会明显影响架构、依赖、公共 API、内容 Schema、兼容性或用户数据，请先通过 GitHub Issues 说明背景与方案，不要直接提交大范围实现。

二、提交 Issue

报告问题

提交前先搜索是否已有相同 Issue。一个可处理的问题报告通常包括：

  1. 出现问题的页面或功能；
  2. 能稳定触发问题的最小步骤；
  3. 实际结果与预期结果；
  4. 浏览器、操作系统和必要的版本信息；
  5. 截图、错误文本或最小复现（如果适用）。

不要只写“不能用”或“显示不对”。越接近可复现事实，问题越容易被定位。

提出内容或功能建议

请说明建议服务于谁、解决什么问题、为什么现有内容或能力不足，以及你考虑过哪些更小的替代方案。视觉效果还应说明对阅读、移动端、浅色 / 深色主题、减少动态效果和性能的影响。

三、建立开发环境

前置要求

  • Node.js 20 或更高版本；
  • Bun 1.0 或更高版本；
  • Git。

Fork 与启动

Bash
# Fork 后克隆自己的仓库
git clone https://github.com/<your-username>/Neoverse-Doc.git
cd Neoverse-Doc

# 保留官方仓库作为 upstream
git remote add upstream https://github.com/SSJ-ZYJ/Neoverse-Doc.git

# 安装依赖并生成 Fumadocs 内容文件
bun install

# 生成 Mermaid 资源并启动开发服务器
bun dev

浏览器打开 http://localhost:3000 即可预览。不要在没有讨论的情况下新增、删除、升级或替换依赖；当前版本以 package.json 为准。

常用命令

命令用途是否写入工作区
bun dev执行内容准备管线并启动开发服务器是
bun lint运行 Biome Lint否
bun typecheck生成路由与内容类型，校验 MDX、Frontmatter 和 TypeScript是
bun run generate:content内容准备管线：校验内容并增量生成 Mermaid 静态 SVG 与资源映射是
bun run build执行内容校验与生产静态构建（不渲染 Mermaid）是
bun format使用 Biome 格式化工作区是
bun check使用带 --write 的 Biome Check是
bun run start预览已经生成的 out/ 静态产物否

bun check 不是只读检查

它会修改工作区文件。执行 bun format、bun check、类型生成、Mermaid 生成或构建后，都应检查 git status 和 Diff，避免把无关变化带进 Pull Request。

四、项目结构

source.config.ts
next.config.ts
package.json
AGENTS.md

开始修改前，请先阅读根目录的 AGENTS.md、受影响文件及其调用方。README 是项目能力与技术栈的总览，实际行为仍以当前代码、配置和内容为准。

五、实现约束

保持最小改动

  • 只修改完成当前目标所必需的文件；
  • 不格式化、移动或重构无关代码；
  • 优先修复根因，不用额外定时器、高权重 CSS 或重复状态掩盖问题；
  • 保留工作区中不属于自己的未提交改动。

保持现有架构

  • Static-first：不得破坏生产静态导出，也不要让核心功能依赖长期服务器、数据库、Server Action 或 Middleware。
  • Server-first：组件默认保持 Server Component，仅在状态、交互或浏览器 API 需要时添加小型客户端边界。
  • Fumadocs-first：页面树、MDX、目录、搜索和 i18n 优先使用现有 Fumadocs API。
  • 类型安全：不要用 any、@ts-ignore 或不安全断言隐藏真实问题。
  • 现有设计系统优先：复用 Token、组件与样式模式，同时检查移动端、浅色 / 深色主题和减少动态效果。

新增用户可见 UI 文本必须接入 src/dictionaries/ 的现有 i18n 体系，并同步当前语言字典。新增依赖需要先说明名称、用途、版本与现有方案不足之处。

命名规范

类型规范示例
文件名小写 + 连字符guestbook.tsx
组件名PascalCaseGuestbook
函数名camelCasegetDictionary
常量UPPER_SNAKE_CASEDEFAULT_LOCALE
CSS 类小写 + 连字符liquid-glass

详细实现原则

视觉、动效、Mermaid、转场、任务与评论等模块的详细实现原则按专题维护，修改对应模块前请先阅读：

六、修改文档

内容位置与文件类型

站点内容位于 content/docs/{locale}/。普通 Markdown 使用 .md；需要 JSX 组件时使用 .mdx。页面已经通过 Frontmatter 提供标题时，正文从 ## 开始。

新增页面后，必须在同目录的 meta.json 中注册。若页面已经存在对应中英文版本，修改核心内容时应同步维护；当前只有中文的页面，不要为了形式完整擅自创建英文版本。

Frontmatter

Frontmatter 必须符合 source.config.ts 的 Schema。除 Fumadocs 基础字段外，项目当前扩展字段包括：

YAML
---
id: ch1/your-page-name
title: 页面标题
description: 页面描述
author:
  - "主要作者(https://github.com/your-name)"
contributors:
  - "贡献者(https://github.com/contributor-name)"
draft: false
todoProgress: false
---

id 是必填的稳定内容身份：新建页面时取与最终路径一致的值（如 ch1/your-page-name），中英文版本必须声明相同 id；此后移动文件或调整 URL 都不要改它。author、contributor 和 contributors 支持单个字符串或字符串数组；draft 与 todoProgress 默认均为 false。不要写入 Schema 未声明的自定义字段。

正文规则

  • 代码块声明正确语言；命令、路径、配置项、API 和环境变量使用反引号；
  • 中文与英文、数字、缩写之间原则上保留一个半角空格；
  • 中文正文使用全角引号“”，代码与配置字符串保留英文引号；
  • 首次出现的陌生术语应就近解释，必要时链接到详细章节；
  • 站内链接使用 /zh/docs/ch1/xxx 或对应 locale 的绝对路径，能定位小节时附标题锚点；
  • Mermaid 只在图形表达明显优于文本时使用；修改图表后重新生成静态资源；
  • 文档中的版本、命令、路径和行为必须能由当前仓库或可靠官方资料验证。

新增站点 MDX 组件时，还要在 src/components/mdx/mdx-preview-shims.tsx 导出，并在 .mdx-previewrc.json 注册，避免 VS Code MDX Preview 将其识别为未知组件。

完整写法与渲染示例见 语法与组件参考。

七、选择验证范围

修改范围至少执行
纯 TypeScript / React / CSS 修改bun lint、bun typecheck
Markdown / MDX 或 Frontmatterbun typecheck
Mermaid 内容或数量变化bun run generate:content，并检查生成资源
静态路由、构建配置或较大内容变更bun run build
使用了写入型格式化命令检查 git status 与完整 Diff

验证应与改动风险匹配，不必机械运行所有命令；但不能声称没有实际执行的检查已经通过。

八、提交 Pull Request

提交前检查

  • 已更新相关文档；
  • 已更新 meta.json（如新增文档）；
  • 代码通过类型检查：bun typecheck；
  • 代码通过 Lint 检查：bun lint；
  • 代码已格式化：bun format；
  • 本地构建成功：bun run build。

bun check（带 --write）会修改工作区文件，不要当作默认只读检查；执行后必须检查 Diff。

建议流程

  1. 从最新 main 创建范围明确的分支；
  2. 完成一组聚焦修改，避免夹带无关格式化；
  3. 检查 git status、完整 Diff 和生成文件；
  4. 执行与修改范围匹配的验证；
  5. 使用清楚的提交信息并推送个人分支；
  6. 创建 Pull Request，说明问题、方案、验证结果和已知风险；
  7. 根据审查意见继续在同一分支修改。

PR 描述应让审查者能够回答：为什么要改、改了什么、怎样验证、哪些内容没有验证，以及是否有截图或复现步骤。

提交信息

提交信息格式为：<修改类型>(<作用域或文件名>): <修改的内容>。如果修改涉及多个文件，使用功能模块的名称作为作用域。

常用修改类型包括：

  • feat：新增功能；
  • fix：修复 bug；
  • docs：文档变更；
  • style：格式化变更（不影响代码运行）；
  • refactor：代码重构（不影响功能）；
  • test：测试变更（不影响功能）；
  • chore：构建过程或辅助工具变更（不影响功能）；
  • ci：持续集成相关变更（不影响功能）；
  • revert：回滚到之前的版本。

摘要部分使用中文，简要描述本次提交改动的内容，并控制在 10 个英文单词以内。改动较多时，在摘要中写出核心变更，并在正文部分详细列出其他内容；存在正文时，在摘要行与正文之间保留一个空行。

例如：

Text
docs(about): 重写贡献指南

补充验证范围表格，并更新提交信息与协作准则。
Text
fix(search): 修复章节筛选状态

PR 标题可以沿用相同格式。

九、翻译原则

  • 先理解原文意图，再按目标语言习惯表达，不做逐词替换；
  • 保持标题层级、链接目标、代码行为和 Frontmatter 结构一致；
  • 统一专业术语，避免同一概念在相邻页面使用不同译名；
  • 代码中的用户可见输出与教学性注释按上下文翻译，语法标识符保持原样；
  • 翻译完成后单独检查 locale 路径、站内链接和页面注册。

添加新语言

  1. 在 src/lib/i18n.ts 的 defineI18n 中注册语言：

    TypeScript
    export const i18n = defineI18n({
  defaultLanguage: 'zh',
  languages: ['zh', 'en', 'ja'], // 新增 'ja'
  parser: 'dir',
  fallbackLanguage: null,
});

  2. 在 src/dictionaries/ 创建语言包文件 ja.ts，并在 src/dictionaries/index.ts 中导入注册；

  3. 在 src/adapters/fumadocs/layout.tsx 添加 fumadocs UI 翻译；

  4. 在 content/docs/ 创建 ja/ 目录并翻译文档；

  5. 完成后单独检查 locale 路由、站内链接与页面注册。

十、协作准则

参与贡献即表示你同意遵守以下原则：

  • 尊重所有贡献者；
  • 接受建设性的批评和建议；
  • 关注对社区最有利的事情；
  • 对他人保持同理心。

尊重其他贡献者及其时间，围绕事实和改动讨论；欢迎建设性批评，也请解释判断依据。不要公开私人信息，不要使用攻击性表达，不要通过大范围无关改动迫使审查者接受目标之外的变化。

感谢你对 Neoverse-Docs 的贡献。遇到不确定的问题时，还请先在 GitHub Issues 中讨论。

后记

何以为学——Neoverse-Docs 项目的后记

语法与组件参考

编写 Neoverse-Docs 时可用的 Frontmatter、Markdown、MDX 组件、公式与图表

本页目录

一、关于贡献二、提交 Issue报告问题提出内容或功能建议三、建立开发环境前置要求Fork 与启动常用命令四、项目结构五、实现约束保持最小改动保持现有架构命名规范详细实现原则六、修改文档内容位置与文件类型Frontmatter正文规则七、选择验证范围八、提交 Pull Request提交前检查建议流程提交信息九、翻译原则添加新语言十、协作准则

讨论区

欢迎分享你的想法与建议