写一页文档
本文说明怎样在网页上修改并提交一页文档。你不需要在电脑上安装任何软件。
概览
本站的每一页都可以在浏览器中编辑。你提交修改后，系统用你的 GitHub 账号创建一个 Pull Request。维护者评审并合并后，修改发布到网站上。
你不需要这个仓库的写权限，也不需要安装 Git、Node 或任何命令行工具。修改错别字、补充内容和新建页面，都可以用这种方法。
如果要修改导航结构、批量处理图片或修改站点代码，要把仓库克隆到本地，方法见配一台能跑本站的电脑。
如果要用 AI 起草，先读用 AI 帮忙写文档。
第一步：打开要修改的页面
在 https://docs.nbtca.space 上打开你要修改的页面。用站内搜索查找最快。
第二步：登录
- 如果没有 GitHub 账号，先在 https://github.com 注册。用教育邮箱注册，还可以申请学生优惠。
- 在页面上单击“登录后在本页编辑”。页面转到 GitHub 授权页。
- 用你的 GitHub 账号登录，单击同意授权。
验证：页面回到文档站，入口文字变为“在本页编辑”。
第三步：修改
单击“在本页编辑”，打开编辑框。
- 用 Markdown 语法编写。常用语法见 Markdown。
- 编辑器会自动检查 Markdown。发现问题时，编辑框上方会列出规则、行号和修改提示；修正前不能提交。
- 要插入图片，把图片拖进编辑框。系统自动把图片转为 WebP 格式并保存。
- 页面开头两行
---之间是元信息。如果你不清楚每一项的作用，不要修改它们。 - 需要画流程图时，用标注为
mermaid的代码块。单击“预览”后，它会像正式页面一样渲染成图表。
如果你不能确定某个事实，写清楚缺少什么，不要编造。归档页有专用的标记，见编者按标记。
第四步：提交
单击“提交”。系统用你的账号复制仓库，把修改放入副本，再自动创建一个 Pull Request。
验证：页面显示一个 PR 链接。打开链接，能看到你的修改。
第五步：等待评审
维护者在 PR 中回复。如果需要修改，在网页上再次修改并提交。同一个 PR 自动更新，不要重新创建 PR。评审通过后，维护者合并 PR。
PR 下方有一组自动检查。检查失败通常是格式问题，不是内容错误。单击失败的检查，查看具体的错误，再按 Markdown 修改。
新建一页
- 单击“登录后新建一页”。
- 选择这一页所属的板块。每个板块旁边说明了它包含的内容和写法。
- 系统生成一个空文档和一份页面结构。
- 修改文件名。系统生成的临时文件名以
draft-开头。
注意
提交前，必须修改文件名。文件名就是这一页的网址。使用可以长期不变的名字，全部小写，用连字符分隔单词。
写作上的几条硬要求
- 站内链接以
/开头，例如/tutorial/markdown。 - 引号用
“”，不要用「」。 - 加粗文字紧邻标点时可能不能正确显示，见强调的边界规则。
- 每张图片都要写
alt。alt描述画面内容，供看不到图片的读者使用。 - 不能确定的事实，留空，不要猜测。
故障排查
| 情况 | 参考 |
|---|---|
| 不确定某种语法怎么写 | Markdown |
| 想用容器、代码组、图注组件 | VitePress |
| PR、评审、标签在 GitHub 上怎么点 | GitHub 工作流 |
| 想弄清 PR 到底是什么 | Git 的理念与模型 |
如果仍然不能解决，在群里提问，或者创建一个 Issue。如果你在某一步卡住，通常是本手册没有写清楚，请补充。