koda-zensical
Навык, который необходим для работы с движком документации Zensical. Для соответствующего проекта обязательно применяй эти инструкции, поскольку они позволят правильно писать и форматировать исходные файлы документации.
XCode-NLP · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add XCode-NLP/KodaSkills --skill koda-zensical技能说明
name: koda-zensical description: "Навык, который необходим для работы с движком документации 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
Синтаксис:
!!! <тип> "Заголовок статичной врезки"
Содержимое, которое может
быть многострочным
??? <тип> "Заголовок разворачиваемой врезки"
Содержимое, которое может быть многострочным
и свёрнуто по умолчанию, но разворачивается по клику на заголовке
???+ <тип> "Заголовок сворачиваемой врезки"
Содержимое, которое может быть многострочным
и развёрнуто по умолчанию, но сворачивается по клику на заголовке
Типы, их цвета и пиктограммы:
| Тип | Цвет | Пиктограмма |
|---|---|---|
note | #448aff | карандаш в круге |
abstract | #00b0ff | планшет для бумаги |
info | #00b8d4 | i в круге |
tip | #00bfa5 | пламя |
success | #00c853 | галочка |
question | #64dd17 | ? в круге |
warning | #ff9100 | ! в треугольнике |
failure | #ff5252 | крестик |
danger | #ff1744 | молния в круге |
bug | #f50057 | жук на щите |
example | #7c4dff | пробирка |
| `quote |