跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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.

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

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

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

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

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

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#00b8d4i в круге
tip#00bfa5пламя
success#00c853галочка
question#64dd17? в круге
warning#ff9100! в треугольнике
failure#ff5252крестик
danger#ff1744молния в круге
bug#f50057жук на щите
example#7c4dffпробирка
`quote
阅读完整来源 ↗