CONTRIBUTING_BOOK.md

Contributing for book

Форматирование

[правило 1.1] Изменение заголовков

Основное правило редактирования контента книги относится к изменению заголовков. Изменяя заголовок в файле book/*/chapters/**/content.md необходимо изменить его в файле описывающем оглавление книги book/*/metadata/toc.json. В противном случае валидатор не позволит сделать коммит.

[правило 1.2] Название директорий

Название директорий должно совпадать с заголовком первого уровня (# Heading) расположенного в файле content.md принадлежащего этой директории.

[правило 1.3] Изменение названия директории

При изменении названия директории содержащей файл content.md также необходимо произвести изменения в файле toc.json.

[правило 1.4] Добавление новой главы

При добавлении новой главы (новой директории) необходимо выполнить следующие шаги: 4.1 Создать директорию, название которой совпадает с заголовком первого уровня находящегося в файле content.md. Стоит обратить внимание, что название директории не должно содержать индекса (000.) и подраздела ((Section Type)).
4.2 Создать в директории созданной на предыдущем шаге файл content.md и заполнить его контентом.
4.3 Создать описание новой главы в файле toc.json и разместить его под индексом соответствующим номеру главы.
4.4 Выполнить в терминале команду npm run book-reindex.

[правило 1.5] Изменение номера главы

Для изменения порядка существующих глав требуется изменение порядка в файле toc.json после чего терминале необходимо выполнить команду npm run book-reindex.

Стиль

[правило 2.1] Заголовки должны начинаться с заглавной буквы

Bad - # text text
Good - # Text text

[правило 2.2] Квадратные скобки в заголовках должны быть экранированы

Bad - # Text [text] text
Good - # Text \[text\] text

[правило 2.3] Скобки в заголовках не должны содержать пробелы

Bad - # Text [ text ] ( text ) < text >
Good - # Text [text] (text) <text>

[правило 2.3] Заголовки не должны содержать более одного пробела

Bad - # Text text
Good - # Text text

[правило 2.4] Заголовок любого уровня имеет отступ в одну строку

Bad -

# Text text
Content

Bad -

# Text text


Content

Good - `

# Text text

Content

[правило 2.5] Блок кода обрамляется пятью косыми кавычками

Bad -

```ts
```

Good -

`````ts
`````

[правило 2.5] Блок кода имеет один отступ с верху и низу

Bad -

content
`````ts
`````
content

Bad -

content


`````ts
`````

content

Good -

content

`````ts
`````

content