编写页面
页面存放在哪里，如何提交修改，以及如何排版页面：文件名、frontmatter、标签、链接、图片、标注框
仓库
项目的所有仓库都在bullet-hero组织下。开放的仓库有：
| 仓库 | 内容 |
|---|---|
| bullet-hero/releases | releases中是游戏的每个公开版本，issues中是玩家反馈的关于游戏的错误和建议 |
| bullet-hero/sdk | SDK代码，issues中是关于SDK的错误和建议 |
| bullet-hero/docs | 这些页面及其翻译 |
| bullet-hero/backend | 服务器，目前是空的 |
游戏（bullet-hero/game）和网站（bullet-hero/frontend）的代码是闭源的
本页讲的是bullet-hero/docs
如何提交修改
- Fork bullet-hero/docs并创建一个分支
- 按下面描述的格式编辑或添加页面
- 在每种语言中修改该页面，或者在pull request中说明哪些语言仍需要这项修改。更多：翻译
- 对照风格指南检查文本
- 发起pull request，简要说明改了什么以及为什么改
事实来自游戏、SDK或它们的文档。数字、字段名、文件名、快捷键和地址从不靠猜。不确定某件事是否正确？在pull request里说明，而不是写在页面上
合并后的修改不会立即出现在bullethero.space上，而是随网站的下一次更新出现
网站代码是闭源的，所以你无法自己构建网站。最接近的预览方式是Obsidian：Obsidian无法解析的链接，在网站上同样无法解析
仓库如何运作
- 只有markdown。没有自己的构建流程，也没有脚本
- 它是一个Obsidian库。把仓库的根文件夹作为库打开，链接、嵌入和预览的效果与网站上相同。其他任何markdown编辑器也可以使用
- 它是网站的子模块。网站把这个仓库作为自己的
content/文件夹引入，在构建时编译页面，并预渲染每一个页面。网站指向本仓库的指针向前移动后，修改才会出现在网站上
内容放在哪里
| 路径 | 内容 | 网站上的地址 |
|---|---|---|
<lang>/docs/1_game/ | 面向玩家：安装、游玩、设置、机制 | /<lang>/docs/game |
<lang>/docs/2_editor/ | 面向关卡作者：编辑器指南和参考 | /<lang>/docs/editor |
<lang>/docs/3_sdk/ | 面向开发者：开源SDK和关卡格式 | /<lang>/docs/sdk |
<lang>/docs/4_server/ | 面向服务器运营者：官方服务器和社区服务器 | /<lang>/docs/server |
<lang>/docs/5_contribute/ | 本章节 | /<lang>/docs/contribute |
<lang>/notes/ | 文章、公开文件和政策，按日期排序 | /<lang>/notes/<name> |
<lang>/tags/ | 标签页面 | /<lang>/tags/<tag> |
<lang>/download.md | 下载页面 | /<lang>/download |
assets/ | 所有语言共用的图片 | 嵌入到页面中 |
<lang>是语言文件夹：en、ru或zh。docs/、notes/、tags/和download.md之外的文件不会成为页面
文档描述的是事物现在如何运作。某样东西如何变化的经过、个人观点或随笔应放在notes/中
文件名和顺序
- 侧边栏中的顺序由
N_前缀决定，docs/内的每个文件和文件夹都有这个前缀：1_、2_，依此类推，直到10_及以上 - 前缀永远不会出现在地址中。
1_game/3_controls.md的地址是/<lang>/docs/game/controls index.md没有前缀。它是所在文件夹的首页，占据文件夹的位置，并为侧边栏中的分组命名- 要调整页面顺序，就重命名文件。在Obsidian中启用“Automatically update internal links”，它会替你修正所有链接
- 去掉前缀后的名称在同一语言内是唯一的。如果两个文件对应到同一个地址，网站构建时会报告
- 带前缀的名称在所有语言中都相同。
en/docs/2_editor/4_craft/3_difficulty-curve.md和zh/docs/2_editor/4_craft/3_difficulty-curve.md是同一个页面 notes/没有前缀，也没有子文件夹。永远不要重命名notes/cookie-policy：网站的Cookie横幅链接到它
Frontmatter、标题和摘要
每个页面都以这样的内容开头：
---
title: Difficulty and the curve
date: 2026-09-24
tags: [level_author]
---
# Difficulty and the curve
One line that says what the page is, up to 200 characters, no markuptitle、H1和摘要用页面所属的语言书写。上面的例子来自英文版- Frontmatter包括
title、date和tags。其他内容一概不读取。date的格式是YYYY-MM-DD，在创建页面时设定 # H1是必需的，且与title相同。网站只显示正文，所以H1就是页面可见的标题- H1之后的第一段是描述，显示在列表、搜索和链接预览中。它会在200个字符处截断。把它写成一行，不带链接和格式
- 章节用
##，小节用###。它们会生成锚点和目录。不需要更深的层级
受众标签
每个文档页面都有1到3个来自此列表的标签。标签用snake_case书写，不带#。网站会在页面上显示它们
| 标签 | 显示为 | 对象 |
|---|---|---|
player | 玩家 | 普通玩家 |
advanced_player | 进阶玩家 | 想了解机制的玩家 |
level_author | 关卡作者 | 在编辑器中制作关卡 |
developer | 开发者 | 基于SDK开发或扩展游戏 |
server_host | 服务器运营者 | 为自己和朋友运行服务器 |
server_advanced | 进阶服务器运营者 | 大型服务器运营者，愿意投入精力扩展或编写服务器 |
contributor | 文档贡献者 | 在本仓库中编辑文本和翻译 |
notes/中的笔记改用主题标签，目前是legal（法律文件）
读者永远看不到标签代码。显示的名称来自标签页面<lang>/tags/<code>.md：
- 它的
title就是显示名称 - 它的第一段描述受众
- 带有该标签的页面列表由网站自动添加
新标签需要在每种语言中都有这样一个页面
要在正文中提到某个标签，就链接到它的页面：[[level_author]]。链接会以读者的语言显示名称
链接
| 目标 | 写法 |
|---|---|
| 另一个页面 | [[3_difficulty-curve]]，使用带前缀的完整文件名 |
| 页面中的某个章节 | [[3_difficulty-curve#Anchor]] |
| 文件夹首页 | [[2_editor/4_craft/index]]，要带路径，因为每个首页都叫index |
| 外部网站 | [text](https://…)，使用带协议的完整地址 |
链接解析到不带语言的地址，所以同一份源文本在所有语言中都能用。[[cookie-policy]]会把英文读者带到英文页面，把俄文读者带到俄文页面，把中文读者带到中文页面
只链接到已经存在的页面。网站构建会报告每一个无法解析的链接
图片
图片放在仓库根目录的assets/中，用![[file.png]]嵌入
所有语言共用一个文件夹。图片中绘制的文字不会随页面一起翻译
标注框
| 语法 | 颜色 | 用途 |
|---|---|---|
> [!note]、> [!info]、> [!tip] | 蓝色 | 背景信息、捷径、建议 |
> [!warning]、> [!caution] | 琥珀色 | 耗费时间或降低质量、毁掉成果 |
> [!danger]、> [!bug] | 红色 | 可以渲染，但风格指南不使用它们 |
选用哪种标注框、它的标题，以及每页最多两个的限制：风格指南
代码和其他标记
- 代码高亮只支持
ts、tsx、js、json、csharp、bash、yaml、css和md。其他语言显示为纯文本 - 可以使用GFM表格、任务列表、脚注和
==highlights== - 不支持MDX和JSX。
{和<会原样显示