Koda Zensical

Документирование Zensical

Принципы написания документации

Язык и стиль

• Пиши простым и понятным языком
• Избегай просторечий и сложных технических терминов без объяснения
• Используй активный залог
• Обращайся к пользователю документации на "вы"
• Поддерживай единый стиль во всех документах
• Не злоупотребляй emoji

Примеры

• Приводи примеры конфигурации
• Показывай скриншоты для важных шагов
• Добавляй таблицы для сравнения опций

Исправление и избегание ошибок

• Синтаксические и грамматические ошибки должны исправляться в соответствии с правиламии и нормами естественного языка
• При изменении структуры документации:
  • в новый документ следует добавить ссылки на другие релевантные документы или якоря
  • ссылки на перемещённый или удалённый документ/якорь следует обновить в каждом существующем документе
  • следует проверять результаты сборки на наличие ошибок и предупреждений компилятора

Синтаксис файлов

В основе документации лежит расширенный markdown.

Ниже описаны правила оформления и синтаксиса, которые отличаются от стандартного markdown и github-flavoured markdown.

Расширения синтаксиса предоставляются связкой:

• zensical (документация: https://zensical.org/docs/)
• pymdown-extensions (документация: https://facelessuser.github.io/pymdown-extensions)

Ниже только необходимые и достаточные правила для:

• качественной документации;
• хорошего человеческого восприятия;
• корректного формирования документации без ошибок.

Применение этих подходов необязательно, но требования к каждому требуется соблюдать строго.

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

Frontmatter

Каждый документ должен начинаться с этого блока метаданных.

После frontmatter должна быть пустая строка.

Внутри должен быть валидный yaml. Часто используются следующие опциональные параметры (* — желательны):

• *title — укорочечнное название документа для отображения в навигации (умолчание — заголовок 1 уровня)
• *description — небольшое осмысленное описание документа (умолчание — пусто)
• *icon — код иконки для отображения в навигации рядом с названием (умолчание — пусто)
• *tags — массив ключевых слов (тегов), описывающих документ (умолчание — пусто)
• hide — массив кодов элементов, которые нужно скрыть на странице документа:
  • navigation — главная навигация (слева)
  • toc — содержание страницы (справа)
  • path — хлебные крошки (сверху)
• status — статус страницы (добавляет к пункту навигации слева иконку с подсказкой)
  • new — новая информация
  • deprecated — устаревшая информация

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

Заголовки

На странице должен быть только один заголовок 1 уровня — сразу после Frontmatter.

До и после каждого заголовка должна быть 1 пустая строка.

В конце строки заголовка должно быть объявление в формате: { id="header-slug" }

Так будет проще связывать секции разных страниц между собой.

Абзацы

До и после каждого абзаца должна быть 1 пустая строка.

Каждое предложение внутри абзаца должно быть на новой строке.

Списки

Вложенные уровни отступаются на 4 пробела слева.

До и после каждого списка должна быть 1 пустая строка.

Ненумерованные списки начинаются с -.

Многострочные блоки кода

Требует дополнительной настройки. Обратись к документации: https://zensical.org/docs/authoring/code-blocks/#code-blocks

До и после каждого блока кода должна быть 1 пустая строка.

Каждый блок кода в заголовке может иметь атрибуты:

• title="..." — заголовок блока (например, название файла)
• hl_lines="..." — подсветка срок: номера через пробел и/или диапазоны через -
• linenums="N" — включить нумерацию строк, отсчитывая с указанного числа N

В конце строк внутри блока может быть любое число в формате #(X)! — это кликальбельные аннотации, содержимое которых будет взято из ближайшего нумерованного списка.

Полный пример:

context:
  - provider: code
  # - provider: docs # сломан
  - provider: diff
  - provider: terminal
  - provider: problems
  - provider: folder
  - provider: codebase
    params:
      nFinal: 10
  # - provider: file
  # - provider: url
  # - provider: search

Врезки

Позволяют акцентировать внимание на ключевых моментах, выделяя блок цветом и иконкой.

Документация: https://raw.githubusercontent.com/zensical/docs/master/docs/authoring/admonitions.md

Синтаксис:

!!! <тип> "Заголовок статичной врезки"
    Содержимое, которое может
    быть многострочным

??? <тип> "Заголовок разворачиваемой врезки"
    Содержимое, которое может быть многострочным
    и свёрнуто по умолчанию, но разворачивается по клику на заголовке

???+ <тип> "Заголовок сворачиваемой врезки"
    Содержимое, которое может быть многострочным
    и развёрнуто по умолчанию, но сворачивается по клику на заголовке

Типы, их цвета и пиктограммы:

Заголовок может быть пустым, в этом случае:

• после типа указываются пустые двойные кавычки (иначе подставится название типа с заглавной буквы на английском языке)
• содержимое внутри блока обрамлён цветом своего типа

Если текста внутри врезки нет, отображается только яркий заголовок с иконкой.

Содержимое врезки отступается минимум на 4 пробела. Содержимое без отступа (в начале строки) находится вне врезки.

Для содержимого врезки распространяются все те же markdown-правила, включая указанные в этом документе.

До и после каждой врезки должна быть 1 пустая строка.

Сниппеты

Это переиспользуемые блоки markdown/html, хранящиеся в файлах.

• Директория: snippets в корне проекта
• Документация: https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/pymdownx/snippets.py

Как использовать:

1. создать файл с директории
2. наполнить содержимым
3. во всех местах документации вставить:
   • пустая строка
   • --8<-- "filename.md"
   • пустая строка
4. если файлов несколько, вставить следующим образом:
   • пустая строка
   • --8<--
   • "filename1.md"
   • пустая строка
   • "filename2.md"
   • --8<--
   • пустая строка

Иконки

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

Внутри frontmatter (параметр icon) используется формат: набор/иконка

В тексте документа используется формат: :набор-иконка:

Если иконка в начале строки, пробел ставится только после неё. Если иконка в середине строки, пробелы ставятся до и после неё. Если иконка в конце строки, пробел ставятся только до неё.

Доступны 4 встроенных набора иконок:

Полный список названий иконок здесь: https://squidfunk.github.io/mkdocs-material/assets/javascripts/iconsearch_index.json

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

<custom_dir>/
    .icons/
        <код_набора1>/
            <код_иконки1>.svg
            <код_иконки2>.svg
            ...
        <код_набора2>/
            <код_иконки3>.svg
            <код_иконки4>.svg
            ...

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

Гриды (карточки)

Грид позволяет разместить короткие предложения в формате динамических карточек.

Он выглядит как markdown-список, обрамлённый в <div>. До открывающего и после закрывающего тегов должна быть 1 пустая строка.

Пример простого грида с компактными карточками:

<div class="grid cards" markdown>
- :fontawesome-brands-html5: Карточка №1
- :fontawesome-brands-js: Карточка №2
- :fontawesome-brands-css3: Карточка №3
- :fontawesome-brands-internet-explorer: Карточка №4
</div>

Пример грида с многострочными карточками:

<div class="grid cards" markdown>
- :fontawesome-brands-html5: **Заголовок карточки №1**

    ---

    Многострочное содержимое карточки №1

- :fontawesome-brands-js: **Заголовок карточки №2**

    ---

    Многострочное содержимое карточки №2

- :fontawesome-brands-css3: **Заголовок карточки №3**

    ---

    Многострочное содержимое карточки №3

- :fontawesome-brands-internet-explorer: **Заголовок карточки №4**

    ---

    Многострочное содержимое карточки №4
</div>

Вкладки (табы)

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

Синтаксис:

=== "Заголовок вкладки 1"
    Содержимое вкладки 1

=== "Заголовок вкладки 2"
    Содержимое вкладки 2

Содержимое вкладки отступается минимум на 4 пробела. Содержимое без отступа (в начале строки) находится вне вкладки.

Для содержимого вкладки распространяются все те же markdown-правила, включая указанные в этом документе.

До и после каждого заголовка вкладки должна быть 1 пустая строка.

После содержимого последней вкладки должна быть 1 пустая строка.

Сноски

Сноска позволяет добавить надстрочный индекс к слову, чтобы вынести пояснения в конец страницы, быстро переместиться к нему по клику на индекс и вернуться обратно.

Синтаксис:

Lorem[^1] ipsum[^2] dolor sit amet, consectetur adipiscing elit.

[^1]: однострочная сноска
[^2]:
    многострочная сноска
    с отступом 4 пробела слева
    на каждой строке

Подсказки (тултипы) и аббревиатуры

Они появляются при наведении мыши на какой-либо элемент на странице документа.

Пример 1: иконка с подсказкой: :material-information-outline:{ title="текст подсказки" }

Пример 2: ссылка с подсказкой: [Hover me](https://example.com "I'm a tooltip!")

Пример 3: альтернативная ссылка с подсказкой:

[Hover me][example]

  [example]: https://example.com "I'm a tooltip!"

Горячие клавиши

В общем случае, для указания корячих клавиш следует использовать тег <kbd>. Примеры: <kbd>B</kbd>, <kbd>Esc</kbd>

Для описания комбинаций клавиш следует вставлять между каждой клавишей знак +, обрамлённый пробелами. Примеры: <kbd>Shift</kbd> + <kbd>A</kbd>, <kbd>Ctrl</kbd> + <kbd>K</kbd> + <kbd>4</kbd>

Для MacOS-специфичных тем вставлять + не нужно. Примеры: <kbd>⌘</kbd><kbd>C</kbd>, <kbd>⇧</kbd><kbd>⌘</kbd><kbd>P</kbd>

Сопоставление пиктограмм с названиями клавиш (служебных и модификаторов) MacOS:

• Базовые модификаторы:
  • ⌘ - Command (Cmd)
  • ⌥ - Option (Alt)
  • ⌃ - Control (Ctrl)
  • ⇧ - Shift
  • ⇪ - Caps Lock
• Навигация и управление:
  • ⌫ - Delete (Backspace, удаление символа слева)
  • ⌦ - Forward Delete (удаление символа справа, Fn + D`elete)
  • ⏎ - Return (Enter)
  • ⌕ - Enter на цифровой клавиатуре (в некоторых шрифтах)
  • ⎋ - Escape (Esc)
  • ⇥ - Tab (Табуляция)
  • ⇤ - Backtab (Shift + Tab)
  • ␣ - Space (Пробел)
• Перемещение по тексту:
  • ↖ - Home (Начало документа, Fn + ←)
  • ↘ - End (Конец документа, Fn + →)
  • ⇞ - Page Up (Страница вверх, Fn + ↑)
  • ⇟ - Page Down (Страница вниз, Fn + ↓)
• Специальные и системные:
  • 🌐 / fn — Функция (Fn / Кнопка смены языка/вызова эмодзи)
  • ⏏ — Eject (Извлечение диска)

Кнопки

• [Серая кнопка](https://example.com/){ .md-button }
• [Синяя кнопка](https://example.com/){ .md-button .md-button--primary }
• [:fontawesome-solid-paper-plane: Кнопка серая с иконкой](https://example.com/){ .md-button }
• [:fontawesome-solid-paper-plane: Кнопка синяя с иконкой](https://example.com/){ .md-button .md-button--primary }