Skip to content

feat(cli): add feedback form#1854

Open
a-shulman wants to merge 1 commit intodiplodoc-platform:masterfrom
a-shulman:feat-feedbackform
Open

feat(cli): add feedback form#1854
a-shulman wants to merge 1 commit intodiplodoc-platform:masterfrom
a-shulman:feat-feedbackform

Conversation

@a-shulman
Copy link
Copy Markdown

Описание

Добавляется расширение для обратной связи по выделенному тексту. Когда пользователь выделяет текст на странице документации, появляется кнопка. По клику на кнопку - форма, где можно сообщить о проблеме:

  • Опечатка
  • Неактуальная информация
  • Нет примера
  • Некачественная графика
  • Другое

Поле Комментарий обязательно для: another, non_relevant, no_example, не обязательно для: typo (опечатка), bad_graphics (плохая графика). Поле Контакт необязательно.

Если расширение включено и настроено, форма отправляет данные на настраиваемый HTTP-эндпоинт + можно навесить счетчики яндекс-метрики на кнокпи (реализовано просто потому, что это у нас уже так работает и нам это нужно).

Если расширение не настроено — оно ничего не делает: скрипты не инжектируются, файлы не копируются.

Что добавлено

  • Серверная часть (src/extensions/feedback/) - класс расширения: CLI-опция, валидация конфига, инъекция скриптов в HTML-вывод через хуки, копирование браузерного бандла в директорию сборки
  • Браузерная часть (src/extensions/feedback/browser/) - IIFE-бандл: отслеживание выделения текста, плавающая кнопка, форма обратной связи, опциональная интеграция с Яндекс.Метрикой
  • Сборка (scripts/build.cli.js) - отдельный esbuild-шаг для браузерного бандла с собственным tsconfig (DOM-типы, без конфликта с Node.js-сборкой)
  • ADR (adr/ADR-007-built-in-text-feedback-extension.md)
  • Тесты - юнит-тесты для хелперов конфига и браузерных утилит, интеграционный тест на инъекцию скриптов в HTML

Использование

Короткая форма — только URL эндпоинта, через CLI-флаг:

diplodoc build -i ./docs -o ./build --text-feedback https://example.com/feedback

Через конфиг .yfm:

# Короткая форма
textFeedback: https://example.com/feedback

# Полная форма — с опциональными счётчиками Яндекс.Метрики
textFeedback:
  endpoint: https://example.com/feedback
  metrika:
    counterId: 12345678
    goals:
      button: my-feedback-button   # цель при клике на кнопку
      submit: my-submit            # цель при отправке формы
      cancel: my-cancel            # цель при отмене

Что инжектируется в каждую HTML-страницу:

<!-- браузерный бандл, загружается до скриптов страницы -->
<script defer src="_extensions/feedback/feedback.js"></script>

<!-- инлайн-скрипт инициализации -->
<script>
  window.feedbackExtensionInit({
    "customFormEndpoint": "https://example.com/feedback",
    "metrika": { "counterId": 12345678, ... }
  })
</script>

Также добавляется CSP-директива connect-src для origin'а эндпоинта.

Как работает

  1. Выделили текст (от 5 символов):
Screenshot from 2026-04-16 18-35-02
  1. Нажали на кнопку:
Screenshot from 2026-04-16 18-35-14
  1. Попытались отправить с незаполненным комментарием, когда это надо:
Screenshot from 2026-04-16 18-35-22

Формат payload'а (POST JSON)

{
  "url": "https://docs.example.com/page",
  "title": "Заголовок страницы",
  "suggestion": "typo | non_relevant | no_example | bad_graphics | another",
  "selected_text": "выделенный текст",
  "comment": "комментарий (опционально)",
  "contact": "контакт (опционально)"
}

P.S. PR вырос из расширения, которое работает уже на нашем сайте (https://docs.ideco.ru/), поэтому некоторые вещи в нем обусловлены именно нашими потребностями. Также важное пояснение: почти весь код расширения нашего и этого пулл-реквеста написан с помощью нейросетей.

@a-shulman a-shulman requested a review from a team as a code owner April 16, 2026 13:37
@a-shulman a-shulman requested review from separatrixxx and removed request for a team April 16, 2026 13:37
uses: actions/setup-node@v4
with:
node-version: 22.21.1
node-version: 22
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please exclude all .github/* files from this PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants