Как писать страницы

Где лежат страницы, как отправить правку и как оформить страницу: имена файлов, 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

Как отправить правку

Сделайте форк 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. Файл вне 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 и ru/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 markup

title, 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/<код>.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. { и < показываются как есть