Последнее обновление 17 мая 2026 г.

Спецификация оформления документации

Этот документ определяет требования к оформлению документации Apache Doris. Он охватывает:

Основные правила оформления имён файлов, URL и структуры документов
Рекомендуемые элементы оформления содержимого документов

Примечание

Независимо от того, редактируете ли вы предыдущую или последнюю версию документации, отправляйте PR в репозиторий apache/doris-website.
Перед отправкой изменений в документацию прочитайте Руководство по участию в разработке документации.

Основные требования к оформлению

Именование файлов и URL

Название документа должно кратко отражать его содержание и не быть слишком длинным. На сайте Doris имя файла также используется в URL, поэтому правила именования файлов связаны с именами элементов в sidebars.json.

Правило	Описание	Пример
Соответствие боковой панели	Имя файла должно совпадать с именем документа в `sidebars.json`	`quick-start`
Только строчные буквы	Используйте в именах файлов только строчные буквы. Не смешивайте регистры и не добавляйте знаки препинания	`standard-deployment`
Дефис в качестве разделителя	Разделяйте несколько английских слов дефисом `-`. Использовать подчёркивание `_` не рекомендуется	`bloom-filter-index`
Исключение для функций	Если в имени конкретной функции используются подчёркивания, следуйте правилам именования этой функции	`array_max`

Правила использования прописных букв в английском тексте

Ситуация	Правило
Заголовки	Пишите с прописной буквы только первое слово заголовка. Все остальные слова, кроме имён собственных, пишите со строчной буквы
Английский текст в китайском предложении	Как правило, используйте CamelCase. Для имён собственных сохраняйте общепринятое написание
Смешанный китайский и английский текст	В китайских документах по возможности используйте китайские выражения. Английский используйте только для отдельных фраз или слов. То же правило действует для английских документов

Правила написания английских имён собственных

Если в китайском документе упоминаются зарубежные бренды, названия продуктов или технические термины, у которых нет официального перевода на китайский язык, используйте английское название с правильным регистром букв. Таблица ниже постоянно пополняется. Вы можете добавить в неё новые записи в своём PR.

Нет официального перевода на китайский язык
GitHub
SQL
CPU
FE
BE
HTTP
MySQL
MongoDB
Elasticsearch
Azure
AWS
S3
Doris Manager
WebUI
Flink Doris Connector

Требования к функциям SQL и справочнику SQL

Ситуация	Правило	Пример
Имена функций SQL	Только прописные буквы. Разделяйте части имени подчёркиванием `_` в соответствии с синтаксическими соглашениями	`ARRAY_MAX`, `DIGITAL_MASKING`
DML / DDL / Типы данных / Управление кластером	Прописные буквы. Разделяйте слова обычным пробелом	`ALTER CATALOG`, `SELECT * FROM`
Примеры и ссылки	Допускаются строчные буквы	`col_name1`, `sample_value`

Требования к структуре документации функций SQL приведены в разделе Руководство по участию в разработке документации: как писать справочник команд.

Правила использования сокращений

Сокращения делятся на китайские и английские. Соблюдайте приведённые ниже правила.

Китайские сокращения: сокращение должно быть понятным и однозначным. Рекомендуется при первом упоминании термина привести его полное название и сообщить читателю, что далее будет использоваться сокращённая форма.

Английские сокращения:

Не расшифровывайте английские сокращения в заголовках
Рекомендуется расшифровывать сокращение при первом упоминании в основном тексте, например Tablet & Partition (в последующих документах называются «разделами и бакетами»)
Не используйте нестандартные сокращения

подсказка

Неправильно	Правильно
16c32g	16 ядер, 32 GB
10w	100,000

Требования к структуре документа

Заголовки

Правильно выбранные уровни и формулировки заголовков помогают читателю понять логику всего документа и сразу увидеть его структуру.

1. Уровни заголовков

В технических документах используется не более двух уровней заголовков. Заголовки основной части начинаются с ##. Не пропускайте уровни.

Уровень	Синтаксис	Описание
Заголовок уровня 1	`{ "title": "", "language": "" }`	Название статьи. Не используйте `#` для задания названия статьи
Заголовок уровня 2	`##`	Заголовок основной части статьи
Заголовок уровня 3	`###`	Подзаголовок внутри раздела с заголовком уровня 2

{
    "title": "Document title (the # level 1 heading)",
    "language": "en"
}


## Level 2 heading

### Level 3 heading

2. Структура формулировок заголовков

Заголовки технических документов могут иметь следующие формулировки, но не ограничиваются ими:

Именная группа, например «Принципы выполнения точечных запросов при высокой конкурентности»
Тема + глагол, например «Развёртывание Docker»
Глагол + тема, например «Каталог файлов конфигурации»
Определение + тема, например «Изменение схемы» или «Руководство пользователя Flink Doris Connector»
Предлог + определение + тема, например «Развёртывание с помощью Doris Operator»

3. Дополнительные замечания

Строгого шаблона для формулировок заголовков нет. Достаточно соблюдать следующие принципы:

Кратко отражайте основное содержание раздела
По возможности используйте одинаковую структуру для заголовков одного уровня
Не повторяйте содержание родительского заголовка в дочернем
Не ставьте знаки препинания в конце заголовка
Не расшифровывайте сокращения в заголовках

Вводный абзац

Вводный абзац располагается перед основной частью. Он должен кратко описывать содержание документа. По возможности ограничьте его объём 150 словами.

Можно использовать один из следующих двух вариантов:

Объяснить, что такое XXX, например: «Data Export представляет собой функцию Doris для экспорта данных. Она позволяет…»
Описать содержание документа, например: «Этот документ знакомит с основными принципами, использованием, рекомендациями и особенностями Data Export»

Элементы содержимого документа (справочно)

Использование табуляции

В технических документах для отступов и выравнивания часто используются клавиша Tab и пробелы. Поэтому рекомендуется:

Использовать Tab для отступов. Не смешивать табуляцию и пробелы в отступах
Во всех редакторах, например Visual Studio Code, задавать единый размер табуляции: один Tab равен четырём обычным пробелам
Учитывать, что отступы влияют на отображение документа. Ориентироваться на отображение в редакторе с форматированным предпросмотром, например VS Code (так, блоки кода внутри структуры с несколькими уровнями отступов иногда нужно размещать без отступа, чтобы они отображались правильно)

Использование пробелов

Добавляйте обычный пробел до и после английского текста или чисел, если они соседствуют с китайским текстом
Добавляйте обычный пробел до и после фрагмента кода, если он соседствует с китайским текстом
Не добавляйте пробелы внутри скобок. Добавляйте обычный пробел перед открывающей и после закрывающей скобки

подсказка

Инструмент для массового добавления обычных пробелов: https://github.com/huacnlee/autocorrect

Нумерованные и маркированные списки

В основной части технических документов часто используются нумерованные и маркированные списки. Нумерованные списки обычно подчёркивают приоритет или порядок пунктов.

Для нумерованного текста рекомендуется использовать формат 1. **Bold ordered text**, чтобы текст выравнивался по родительскому уровню без отступа
Если нумерованный текст содержит маркированный список, выделяйте нумерованный текст полужирным, а маркированный оставляйте без выделения

Ссылки

Ссылки в документе направляют читателя к связанным документам или внешним сайтам. Рекомендуется соблюдать следующие правила:

Описание ссылки: используйте единый стиль описания ссылок одного типа. Избегайте многократного повторения в одном документе фраз вроде «подробнее см.», «подробности приведены в» и «подробности можно найти по адресу»
Формат ссылки:
- Ссылка на другой заголовок в том же документе: [Inverted Index]
- Ссылка на соседний документ: [BITMAP Index]
- Ссылка на внешний сайт: [Wikipedia - Inverted Index](https://en.wikipedia.org/wiki/Inverted_index)
Путь ссылки:
- В пределах одного документа рекомендуется последовательно использовать либо относительные, либо абсолютные пути. Не смешивайте их
- Рекомендуется сокращать число переходов на внешние сайты, чтобы недоступность внешней страницы не мешала читателю. Если ссылка на внешний сайт необходима, рекомендуется предупредить читателя о переходе, например: «Нажмите, чтобы перейти на XXX»

Блоки кода и комментарии в коде

При вставке блоков кода соблюдайте следующие правила:

Используйте один обратный апостроф (`) для встроенного кода. Для многострочного кода используйте три обратных апострофа
Добавляйте пробел до и после встроенного кода. Отделяйте многострочный код от основного текста пустой строкой
Следите за отступами блоков кода. Если блок кода расположен внутри пункта нумерованного или маркированного списка, добавляйте ему отступ относительно уровня этого пункта
Для многострочного кода рекомендуется добавлять ограждение блока и указывать язык кода, чтобы включалась соответствующая подсветка синтаксиса

Распространённые языки и их обозначения в ограждении блока кода:

Тип кода	Обозначение в ограждении блока
Скрипт Shell	```shell
Код Python	```python
Код JSON	```json
Документ XML	```xml
Запрос SQL (используйте строчные буквы в `sql`, иначе отображение будет некорректным)	```sql
Файл YAML	```yaml или ```yml
Текст Markdown	```markdown или ```md
Код JavaScript	```js или ```javascript
Код Java	```java
Код C++	```cpp
Код C	```c
Код Ruby	```ruby
Код HTML	```html
Код CSS	```css
Код PHP	```php

При использовании блоков кода shell приводите вводимую команду и результат её выполнения отдельно. Ниже приведён пример из документации по доступу к кластеру Kubernetes:

Используйте следующую команду для проверки соответствующего Service:
```
kubectl get pod --namespace doris
```

Результат выполнения:

NAME                     READY   STATUS    RESTARTS   AGE
doriscluster-helm-fe-0   1/1     Running   0          1m39s
doriscluster-helm-fe-1   1/1     Running   0          1m39s
doriscluster-helm-fe-2   1/1     Running   0          1m39s
doriscluster-helm-be-0   1/1     Running   0          16s
doriscluster-helm-be-1   1/1     Running   0          16s
doriscluster-helm-be-2   1/1     Running   0          16s

Блоки примечаний

Блоки примечаний используются для выделения содержимого в техническом документе. При их использовании соблюдайте следующие правила.

Тип	Назначение	Синтаксис
Совет	В основном используется для практических советов	`:::tip Tip`
Информация	Используется для дополнительного материала или пояснений	`:::info Note`
Предупреждение	Используется для предупреждений о действиях или моментах, требующих внимания	`:::caution Caution`

Блоки примечаний могут содержать нумерованные списки, маркированные списки и блоки кода.

Пример блоков примечаний в документе Markdown:

:::tip[Tip]
This is a tip
:::

:::info[Note]
This is a note
:::

:::caution[Caution]
This is a caution
:::

Изображения

При вставке изображения соблюдайте следующие правила:

Используйте содержательные имена изображений, например Broadcast Join Principle
Добавляйте альтернативный текст при вставке изображения. Рекомендуемый синтаксис: ![Alt text description](https://example.com/your-image.png)

Для выравнивания изображения по центру используйте:

<div style={{textAlign:'center'}}>
<img src="image URL" alt="text description" style={{display: 'inline-block'}}/>
</div >

Таблицы

Для переноса строки внутри ячейки таблицы используйте <p>XXXX</p>.

Сворачиваемые блоки

Сворачиваемые блоки используются после заголовка уровня 3. Если уровней содержимого слишком много, их можно разделить с помощью сворачиваемого блока.

Соблюдайте следующие правила:

Используйте синтаксис <details><summary>Collapsible box title</summary> Collapsible box content</details>
Следите за отступом сворачиваемого блока. Под заголовком уровня 3 начинайте его с крайней левой позиции

Пример сворачиваемого блока в Markdown:

<details>
<summary>Fill in the title here</summary>
This is the collapsible box content
<p>To add a line break, use an HTML tag</p>
<p>XXXXXXXX</p>
</details>

Переключатель вкладок

Переключатель вкладок используется после заголовка уровня 3. Если в документе слишком много уровней содержимого, можно использовать контейнер с переключателем вкладок.

Соблюдайте следующие правила:

Следите за отступом переключателя вкладок. Под заголовком уровня 3 начинайте его с крайней левой позиции
Используйте следующий синтаксис:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="Content title 1" label="Content title 1" default>
    <p>Content 1 </p>
    <p>Content 2 </p>
  </TabItem>
  <TabItem value="Content title 2" label="Content title 2" default>
    <p>Content 1 </p>
    <p>Content 2 </p>
  </TabItem>
</Tabs>

Метки версий

В новой документации не рекомендуется использовать метки версий для разграничения нескольких версий документа. Если необходимо указать, что функция зависит от версии, используйте блок примечания :::tip :::.

Цитаты

В новой документации не рекомендуется использовать символ цитаты > для описания содержимого или создания вложенности. Если нужно добавить примечание, используйте блок :::info :::.

Основные требования к оформлению​

Именование файлов и URL​

Правила использования прописных букв в английском тексте​

Правила написания английских имён собственных​

Требования к функциям SQL и справочнику SQL​

Правила использования сокращений​

Требования к структуре документа​

Заголовки​

Вводный абзац​

Элементы содержимого документа (справочно)​

Использование табуляции​

Использование пробелов​

Нумерованные и маркированные списки​

Ссылки​

Блоки кода и комментарии в коде​

Блоки примечаний​

Изображения​

Таблицы​

Сворачиваемые блоки​

Переключатель вкладок​

Метки версий​

Цитаты​

Связанные документы​