Skip to content

markdown-style-guide.md

Latest commit

 

History

History
430 lines (302 loc) · 23.2 KB

markdown-style-guide.md

File metadata and controls

430 lines (302 loc) · 23.2 KB

Markdown Style Guide

Формат Markdown отлично подходит для документации. Его легко читать и изменять без применения специальных редакторов.

Этот кодстайл помогает нам достичь трёх целей:

  1. Markdown документы легко читать не только в отрендеренном виде, но и в исходном коде.
  2. Документы легко поддерживать - редактировать, проводить ревью. Стиль на разных проектах не отличается.
  3. Синтаксис простой и запоминаемый.

Перед прочтением кодстайла ознакомьтесь с синтаксисом Markdown:

  • Синтаксис Markdown - синтаксис, который поддерживается везде
  • CommonMark - спецификация Markdown, совместимая с большинством платформ
  • GitHub Flavored Markdown - дополнительные возможности, которые добавляет GitHub
  • GitLab Flavored Markdown - дополнительные возможности, которые добавляет GitLab
  • VuePress Extensions for Markdown - дополнительные возможности для работы с Markdown в VuePress

Частично пункты кодстайла взяты из Markdown style guide от Google.

Оглавление:

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

Используем lower_snake_case за исключением общепринятых имён файлов: README.md, CHANGELOG.md, LICENSE.md, CONTRIBUTING.md и т.д.

Имя файла должно отражать его содержимое и в идеальном случае совпадать с заголовком документа. Исключение - файлы README.md и index.md, которые отображаются при открытии каталога по умолчанию.

Если внутри каталога важен порядок Markdown файлов, используйте цифры в качестве префикса имени файла:

guide
├── 01_getting_started.md
├── 02_configuration.md
├── ...
└── 12_changelog.md

Язык документа

Выбор русского или английского языка для документа зависит от области применения. Английский язык следует выбрать, если вы не хотите ограничивать применение документа русскоязычной аудиторией, например если это документация к библиотеке. В остальных случаях лучше выбрать русский язык, чтобы снизить порог входа и исключить недопонимание из-за языкового барьера.

Структура файла

Для большинства документов достаточно такой структуры:

# Заголовок документа

Краткое вступление.

Оглавление (TOC)

## Заголовок раздела

Содержимое раздела.
  • # Заголовок документа: в идеале должен совпадать или почти совпадать с названием файла, если документ написан на английском
  • Краткое вступление: вступление из нескольких предложений, которое даёт понимание о содержании документа. Представьте, что вы не знакомы с темой, описанной в документе. Прочитав вступление вы должны понять о чем этот документ и для чего он написан.
  • Оглавление (TOC): предоставляет механизм навигации к нужной теме. Подробнее способы создания оглавления рассмотрены в отдельном разделе - "Оглавление".
  • ## Заголовок раздела: заголовки, начиная со второго уровня.

Хорошая практика - оставлять ссылки на дополнительные материалы, относящиеся к теме, в конце документа. Так вы поможете пользователям, которые хотят глубже погрузиться в тему или не нашли нужную информацию в вашем документе.

Оглавление

На платформах с поддержкой Markdown часто есть поддержка автоматической генерации оглавления. Например, в GitLab нужно для этого использовать тег [[_TOC_]]:

Краткое вступление.

[[_TOC_]]

## Заголовок раздела

При просмотре отрендеренного документа вместо тега [[_TOC_]] отобразится оглавление со ссылками на разделы.

Функция генерации оглавления не входит в спецификацию CommonMark, поэтому её реализация отличается в зависимости от платформы:

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

Перенос строки

Ограничения по длине строки нет. Для удобства чтения файлов, используйте редактор, который поддерживает "soft wrapping" - когда длинная строка визуально отображается на нескольких строках, но физически остаётся одной строкой.

Перенос после предложения

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

Если вы используете перенос по длине строки, при изменении одной строки в параграфе скорее всего придётся вносить изменения и во все следующие за ней строки. Худший случай - изменение длины первой строки:

- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras a ullamcorper
- enim, eu eleifend elit. Orci varius natoque penatibus et magnis dis parturient
- montes, nascetur ridiculus mus. Praesent quis magna ipsum.
+ Lorem ipsum dolor sit amet, consectetur. Cras a ullamcorper enim, eu eleifend
+ elit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur
+ ridiculus mus. Praesent quis magna ipsum.

Если использовать перенос по предложениям, будет изменена только одна строка:

- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+ Lorem ipsum dolor sit amet, consectetur.
  Cras a ullamcorper enim, eu eleifend elit.
  Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
  Praesent quis magna ipsum.

Принудительный перенос строки

Спецификация CommonMark даёт нам два варианта переноса строки внутри параграфа:

  1. Добавление двух и более пробелов в конце строки
  2. Добавление обратного слеша (\) в конце строки

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

Для переноса строки не используем HTML тег <br />. Параграфы разделяем пустыми строками.

Заголовки

Стиль заголовков - ATX

## Heading 2

Всегда используем заголовки в стиле ATX (с #). Заголовки в стиле SETEXT (с - и =) сложнее поддерживать:

  • при изменении длины заголовка, нужно изменить и строку под заголовком, если хочется чтобы заголовок оставался красивым
  • чтобы поменять уровень заголовка, нужно заменить все символы под заголовком, в то время как для стиля ATX достаточно добавить или убрать один символ
  • в стиле SETEXT можно объявить заголовки только 1-го и 2-го уровня, для заголовков 3-го и дальше уровня всё равно придётся использовать ATX
  • легко перепутать уровень заголовка.
Heading 1 or 2?
---------------

Отступы вокруг заголовка

Отделяем заголовок от остального текста пустыми строками:

Текст перед заголовком.

## Заголовок

Текст после заголовка

Без отступов заголовок сливается с текстом и становится менее заметен:󠁇

Текст перед заголовком.

## Заголовок
Текст после заголовка. Не делайте так, нужно добавить пустую строку перед текстом.

Списки

Списки отделяем от остального текста документа пустыми строками. Тогда изменения вносимые в список в диффах не будут смешиваться с изменениями текста документа:

Текст документа.

- Item 1
- Item 2

Продолжение текста.

Ленивая нумерация списков

Для нумерованных списков, которые могут изменяться используем ленивую нумерацию. Такие списки проще поддерживать, потому что при добавлении нового элемента в список индексы последующих элементов не изменятся:

1. Item A
1. Item B
  1. Item B.1
  1. Item B.2
1. Item C

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

1. Item A
2. Item B
3. Item C

Фрагменты кода

Inline

Используйте `бэктики` для выделения кода и имен файлов и пакетов внутри абзаца:

Чтобы обновить оглавление в файле `README.md`,
запустите команду `doctoc README.md`.

Не стоит заключать в бэктики названия библиотек или технологий:

Мы используем `Kotlin` и бэктики где ни попадя.
Не делайте `так`.

Блоки кода

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

```kotlin
dependencies {
    implementation(platform(kotlin("bom", version = 1.5.21)))
}
```

Всегда указывайте язык для блоков кода, тогда будет работать подсветка синтаксиса.

Отступ в 4 пробела тоже интерпретируется как блок кода. У таких блоков нельзя указать язык, но они выглядят немного чище в коде. Используйте блоки кода с отступами если нужно написать несколько однострочных сниппетов подряд:

Установите YARN:

    npm install -g yarn

После этого установите зависимости:

    yarn install

Теперь можно запустить локальный сервер с документацией:

    yarn docs:dev

Блоки кода следует отделять от остального текста пустыми строками. Тогда изменения вносимые в блоки кода в диффах не будут смешиваться с изменениями текста документа:

Текст документа.

```markdown
В Markdown можно делать **жирный текст** или *курсив*.
Или ***всё вместе***.
```

Продолжение текста.

Ссылки

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

Информативные названия ссылок

Названия ссылок вроде "ссылка" или "тык" не информативны и ни о чем не говорят при беглом просмотре документа. В большинстве случаев такие названия только занимают место и их можно опустить.

Кодстайл можно посмотреть по [ссылке](style_guide.md).
Кстати, там написано, что такие ссылки не информативны ([тык](style_guide.md#links)).

Лучше писать предложение как будто ссылки нет, а потом превратить в ссылку наиболее подходящую фразу:

Посмотрите [кодстайл](style_guide.md) перед тем как редактировать документацию.
Кстати, там есть [секция "Ссылки"](style_guide.md#links), описывающая как правильно оформлять ссылки.

Алиасы ссылок

Спецификация CommonMark позволяет объявлять алиасы ссылок (link reference):

[Алиасы ссылок][link-alias] это очень удобно.

[link-alias]: https://spec.commonmark.org/0.30/#link-reference-definition

Используя алиасы вместо ссылок мы получаем несколько преимуществ:

  • текст со ссылками выглядят аккуратнее и его проще читать
  • алиасы можно использовать несколько раз, при этом не нужно в каждом месте использования писать ссылку
  • все ссылки собраны в одном месте в конце документа и их проще проверять на актуальность и обновлять.

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

Текст документа.

[01]: docs/01_getting_started.md
[02]: docs/02_configuration.md

[sqlite]: https://sqlite.org/

Для консистентности все алиасы называем в lower-kebab-case. Алиасы не чувствительны к регистру и если алиас совпадает с названием ссылки, его можно опустить. В некоторых случая ссылки можно объявлять более компактно:

[CommonMark] - это наиболее распространённая спецификация Markdown.

[commonmark]: https://commonmark.org

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

## Документация

- [Соглашения](conventions.md)
- [Архитектура](arch.md)

## Полезные ссылки

- [Jira](https://jira.superproject.com/)

Изображения

Markdown поддерживает вставку изображений в документ:

Смотрите какая милота:\
![Кот в халате](https://cdn2.thecatapi.com/images/d60.jpg)

Хорошая практика - сохранять картинки в каталог рядом с документом и добавлять изображение используя относительную ссылку. В этом случае вы будете уверены, что картинка не пропадёт из документа:

Схема интеграции с сервисами заказчика:\
![Схема интеграции](assets/integrations.png)

Ссылка изображения

По умолчанию нажатие на картинку открывает файл с картинкой. Сделать картинку некликабельной не получится, но можно переопределить ссылку:

# Bat Bunker

[![Logo](assets/logo.png)](#)\
(Попробуйте нажать на логотип, у вас ничего не получится)

Наши спонсоры (логотипы кликабельны):\
[![Wayne Enterprises](assets/logo_wayne.png)](https://wayne.enterprises/)