IPTV/docs

Fork 0

Files

T

anthony f25e128299

wip7

2026-07-16 12:07:22 +08:00

19 KiB

Raw Blame History

name, description

name	description
koda-zensical	Навык, который необходим для работы в этом репозитории и должен закружаться безусловно. Этот навык содержит инструкции, которые позволят правильно писать и форматировать исходные файлы документации.

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

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

Язык и стиль

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

Примеры

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

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

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

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

В основе документации лежит расширенный 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 — устаревшая информация
- beta — информация о нестабильном функционале

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

Заголовки

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

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

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

Абзацы

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

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

Списки

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

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

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

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

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

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

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

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

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

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

1. Подсказка 1
2. **Подсказка** 2

Врезки

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

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

Синтаксис:

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

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

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

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

Тип	Цвет	Пиктограмма
`note`	#448aff	карандаш в круге
`abstract`	#00b0ff	планшет для бумаги
`info`	#00b8d4	`i` в круге
`tip`	#00bfa5	пламя
`success`	#00c853	галочка
`question`	#64dd17	`?` в круге
`warning`	#ff9100	`!` в треугольнике
`failure`	#ff5252	крестик
`danger`	#ff1744	молния в круге
`bug`	#f50057	жук на щите
`example`	#7c4dff	пробирка
`quote`	#9e9e9e	двойная кавычка

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

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

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

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

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

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

Сниппеты

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

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

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

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

Иконки

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

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

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

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

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

Название	Код набора	Ссылка	Путь в проекте
Lucide	`lucide`	https://lucide.dev/icons/	-
Material Design	`material`	https://pictogrammers.com/library/mdi/	-
FontAwesome	`fontawesome`	https://fontawesome.com/search	-
Octicons	`octicons`	https://primer.style/octicons/	-
Simple Icons	`material`	https://simpleicons.org/	-
VSCode Codicons	`vscode`	https://github.com/microsoft/vscode-codicons	`./overrides/.icons/vscode`

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

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

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

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

Он выглядит как 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 }

19 KiB Raw Blame History

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

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

Язык и стиль

Примеры

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

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

Frontmatter

Заголовки

Абзацы

Списки

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

Врезки

Сниппеты

Иконки

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

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

Сноски

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

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

Кнопки

19 KiB

Raw Blame History