--- metadata: - property: og:type content: article - property: article:section content: Платформа плагинов - property: og:title content: Публикация и справка плагина - property: article:tag content: Техническая инструкция - name: generator content: Diplodoc Platform v5.66.1 alternate: - https://yandex.ru/support/tracker/en/plugins/publish.md - https://yandex.ru/support/tracker/ru/plugins/publish.md - href: https://yandex.ru/support/tracker/ru/plugins/publish.md type: text/markdown title: Markdown version - href: https://yandex.ru/support/tracker/ru/llms.txt?revision=r22057024 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/ru/llms.txt?revision=r22057024 # Как подготовить плагин к публикации Пользователи Трекера могут найти и подключить плагины в каталоге: [Расширить возможности Трекера с помощью плагинов](https://yandex.ru/support/tracker/ru/user/plugin-catalog.md). Перед публикацией прочитайте [Соглашение с разработчиком плагинов для каталога плагинов сервисов Яндекс 360](https://yandex.ru/legal/360_plugin_dev_agreement/ru/). Чтобы добавить разработанный вами плагин в каталог: 1. Подготовьте для плагина описание и изображения. 1. Подготовьте справку — документацию для пользователей. 1. Отправьте плагин на публикацию. После автоматической модерации плагин появится в каталоге вашей организации с запросом на подключение. Администратору организации нужно будет его одобрить. Разработанный в организации плагин можно добавить в публичный каталог, чтобы он стал доступен пользователям других организаций. Способ публикации зависит от того, опубликован ли плагин в каталоге организации. [Как опубликовать плагин в публичном каталоге](#public-publish). ## Оформление карточки {#card} Перед публикацией добавьте в проект изображения и описание для карточки плагина: - `public/logo.svg` — логотип плагина, должен иметь квадратную форму; - `marketplace/header-image.jpg` — изображение для карточки плагина, должно иметь пропорции 2,41:1. Не дублируйте на изображении название плагина — оно уже есть на странице; - `marketplace/index.md` — описание для карточки плагина. ### Название {#title} - Используйте от 3 до 32 символов. - Пишите название на русском языке. Исключение — официальные названия брендов и продуктов, например Figma или Miro. - Не добавляйте в название слова «плагин», «виджет», «приложение» и похожие обозначения. - Не называйте плагин только по имени сервиса, с которым он интегрируется. - Не используйте название, которое совпадает с названием существующего плагина или приложения более чем на 90%. - Не ставьте точку в конце. Для интеграции с внешним сервисом составьте название по схеме «функция + сервис». Например: _Отправка сообщений в Telegram_. ### Краткое описание {#synopsis} Краткое описание отображается в карточке плагина в каталоге. Оно должно дополнять название и объяснять основную функцию плагина. - Напишите одно-два предложения общей длиной до 75 символов. - Не ставьте точку в конце. Например: - название — _Скрытые заметки_; - краткое описание — _Приватное пространство для заметок внутри задачи с гибкими правами доступа_. ### Полное описание {#full-description} Полное описание должно содержать не более 4000 символов. В него можно добавлять маркированные и нумерованные списки. Не добавляйте внешние ссылки и рекламу. Не дублируйте название плагина — оно уже есть на странице. Рекомендуемая структура полного описания: 1. Какие задачи решает плагин. Перечислите его основные возможности. 1. Для кого предназначен плагин. Укажите роли или должности пользователей, которым он будет полезен. 1. Как использовать плагин. Добавьте краткую инструкцию или сценарий использования. ### Стиль и тон текста {#text-style} - Пишите нейтрально и информативно. Не используйте рекламные обещания, превосходную степень и неподтвержденные оценки, например «лучший» или «№ 1». - Используйте буквы, цифры, одиночные пробелы и необходимые знаки препинания. Не добавляйте эмодзи, восклицательные знаки и специальные символы, например `@`, `#`, `$`, `%`, `^`, `&`, `*`. - Не используйте прописные буквы для выделения текста. Исключение — аббревиатуры длиной не более четырех букв, например API или CRM. - Пишите нарицательные существительные со строчной буквы. - Не сокращайте слова. - Названия брендов и продуктов пишите так же, как на их официальных сайтах и в документации. - Различайте дефис и тире. Например, правильно: _Харон — экспорт данных_; неправильно: _Харон - экспорт данных_. - Используйте букву `ё`, если без нее слово можно прочитать неправильно, а также в редких словах и именах собственных. ## Категория плагина {#category} Для удобства поиска плагины в каталоге группируются по категориям. При создании или публикации плагина нужно указать категории. Категории задаются в [манифесте](https://yandex.ru/support/tracker/ru/plugins/common.md#manifest) в поле `categories`. Полный список доступных категорий: #| || Slug | Название || || `integrations` | Интеграции || || `analytics` | Аналитика || || `planning` | Планирование || || `development` | Разработка || || `automations` | Автоматизации || || `productivity` | Продуктивность || || `entertainment` | Развлечения || || `ai-assistants` | ИИ-помощники || || `support` | Поддержка || || `security` | Безопасность || |# ## Справка плагина {#docs} Справка — это документация вашего плагина для пользователей. Она отображается в каталоге плагинов и в точке интеграции в интерфейсе Трекера. Существует два способа подключить справку: разместить её на внешнем домене или включить прямо в дистрибутив плагина. ### Внешняя справка {#external-docs} Если документация уже размещена на вашем домене, укажите ссылку на неё в поле `docsUrl` файла `manifest.json`: ```json { "docsUrl": "https://example.com/docs/plugin.html", "slots": { "tracker": { "issue.action": [ { "entrypoint": "index.html", "contextLevel": "basic", "title": { "ru": "Мой плагин", "en": "My Plugin" } } ] } } } ``` Трекер отобразит ссылку на справку в каталоге плагинов и в точке интеграции вашего плагина. ### Внутренняя справка {#internal-docs} Если вы хотите включить документацию прямо в дистрибутив плагина, создайте папку `docs/` в корне проекта и разместите в ней файлы `index.md` и `toc.yaml`. Файл `toc.yaml` описывает структуру документа: ```yaml title: My Docs href: index.md items: - name: Introduction href: index.md - name: Getting Started href: getting-started.md - name: Reference href: reference.md ``` #### Структура файлов {#file-structure} Минимальная структура для одностраничной справки: ``` docs/ ├── toc.yaml └── index.md ``` ### Превью {#preview} Если вы хотите посмотреть, как документация будет выглядеть — запустите команду `build-docs` и откройте `docs-build/index.html` в браузере. ### Публикация справки {#publishing} При [публикации плагина](#publish) справка автоматически собирается с помощью [Diplodoc](https://diplodoc.com/docs/ru/). После успешной проверки в манифест плагина будет проставлена ссылка `/docs/index.html`. {% note info "" %} Если корневой файл справки называется не `index.md`, укажите ссылку на него в поле `docsUrl` манифеста вручную. Замените `index.html` на имя вашего файла с расширением `.html`. Например: `"docsUrl": "/docs/my-guide.html"`. {% endnote %} Справка не встраивается в интерфейс Трекера — пользователь переходит по ссылке, как и в случае с внешней справкой. ## Публикация плагина в организации {#publish} Чтобы отправить плагин на публикацию: 1. Получите токен для CLI: ```bash weavix login ``` 3. Запустите публикацию: ```bash weavix submit ``` Команда сама выполнит регистрацию плагина при необходимости, загрузку дистрибутива и отправку версии на модерацию. 4. После отправки на модерацию проверяйте статус публикации: ```bash weavix list ``` Чтобы посмотреть замечания модератора к версии плагина, выполните команду: ```bash weavix info ``` Команда покажет замечания под соответствующей версией с именем автора и датой. В выводе `weavix list` замечания не отображаются. ## Публикация в публичном каталоге {#public-publish} Публичность — свойство плагина, а не отдельной версии. Способ публикации зависит от текущего состояния плагина. {% note warning "Важно" %} Публичный плагин нельзя снова сделать доступным только своей организации. {% endnote %} {% note info "" %} Если CLI сообщает, что установленная версия больше не поддерживается, обновите его: ```bash weavix upgrade ``` Если команда недоступна, переустановите последнюю версию: `npm i -g @weavix/cli@latest`. {% endnote %} ### Перед публикацией плагина {#public-requirements} Команды `submit --public` и `make-public` проверяют, что в карточке плагина указаны: - `name`, `description`, `support`, `categories` и `slug` в `manifest.json`; - `marketplace/index.md`; - `marketplace/header-image.jpg`. Поля манифеста описаны в разделе [Описание плагина в `manifest.json`](https://yandex.ru/support/tracker/ru/plugins/common.md#manifest). Обе команды также проверяют архив на секреты. Если CLI найдет возможные секреты, исправьте их или отметьте ложные срабатывания в интерактивном списке. CLI выводит отпечаток (`fingerprint`) для каждого срабатывания. При любом запуске `make-public` нужно подтвердить необратимое изменение видимости. Чтобы пропустить подтверждение, добавьте флаг `--yes`. При запуске без терминала этот флаг обязателен. При запуске без терминала явно подтвердите отпечатки ложных срабатываний: ```bash weavix make-public --yes --ack ``` Если при неинтерактивном запуске `submit --public` найдены возможные секреты, плагин уже зарегистрирован. Используйте идентификатор плагина и отпечатки из вывода CLI в команде выше, а затем отправьте версию командой `weavix submit`. ### Новый или еще не опубликованный плагин {#submit-public} Выполните команду: ```bash weavix submit --public ``` CLI зарегистрирует плагин, переключит его видимость на `PUBLIC` и отправит версию на модерацию Яндекса. После одобрения версия появится в публичном каталоге и станет доступна пользователям всех организаций. Если плагин уже публичный, отправляйте новые версии командой `weavix submit` без флага `--public`. Если плагин уже опубликован в каталоге организации, CLI завершит команду с ошибкой и сообщит, что нужно выполнить `make-public`. Команду `make-public` можно выполнить и для зарегистрированного, но еще не опубликованного плагина: она сразу переключит видимость на `PUBLIC`, но не отправит версию. После этого отправьте версию командой `weavix submit`. ### Плагин, опубликованный в организации {#make-public} Чтобы опубликовать в публичном каталоге последнюю версию, одобренную организацией, выполните команду: ```bash weavix make-public ``` Если нужно опубликовать другой плагин, укажите его идентификатор: ```bash weavix make-public ``` Если карточка плагина заполнена не полностью, заполните данные из списка CLI. Затем отправьте новую версию командой `weavix submit` и дождитесь одобрения организации. После этого снова выполните `weavix make-public`. После создания заявки отправка новых версий блокируется до решения модератора. Если выполнить `submit` в это время, CLI сообщит об ошибке и предложит отозвать заявку. Посмотреть последнюю заявку можно командой: ```bash weavix info ``` Команда покажет идентификатор и статус заявки, идентификатор версии, даты подачи и решения, а также комментарий модератора. #| || **Статус** | **Описание** || || `PENDING` | Заявка ожидает решения. Отправка новых версий заблокирована || || `APPROVED` | Заявка одобрена, плагин стал публичным || || `REJECTED` | Заявка отклонена с комментарием, плагин остался доступен только организации || || `WITHDRAWN` | Разработчик отозвал заявку || || `OBSOLETE` | Заявка потеряла актуальность без решения || |# Чтобы отозвать активную заявку и снова разрешить отправку версий, выполните команду: ```bash weavix withdraw --publication ``` Для другого плагина передайте его идентификатор: `weavix withdraw --publication `. ## Добавление в каталог {#catalog} После автоматической модерации плагин появится в каталоге вашей организации с запросом на подключение. Администратору организации нужно будет его одобрить. После подтверждения администратором плагин станет доступен пользователям организации так же, как плагины из публичного каталога. [Как подключить плагин](https://yandex.ru/support/tracker/ru/user/plugin-catalog.md) Чтобы плагин, созданный для вашей организации, стал доступен всем пользователям Трекер, [опубликуйте его в публичном каталоге](#public-publish). После одобрения Яндексом плагин появится в публичном каталоге.