vitepress-plugin-report-issue

Ctrl+Enter на любой странице VitePress открывает модальное окно, которое собирает URL, заголовок текущей страницы и выделенный фрагмент в предзаполненную ссылку /<owner>/<repo>/issues/new?title=...&body=...&labels=... на Forgejo/Gitea. Пользователь дожимает "Создать" уже в интерфейсе трекера, где залогинен.

Без бэкенда, без токенов, без CORS -- плагин только собирает URL и передаёт браузеру. Всё, что нужно репортёру ошибок в документации, -- прочитать страницу, выделить проблемный кусок и нажать сочетание клавиш.

Установка

bash

pnpm add @ampernic/vitepress-plugin-report-issue

Пакеты скоупа @ampernic публикуются в реестр Forgejo. Если ставите не из npm, добавьте .npmrc в корень проекта:

@ampernic:registry=https://altlinux.space/api/packages/ampernic/npm/

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

Регистрируется как Vue-плагин в enhanceApp; диалог монтируется один раз в лэйауте.

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import ReportIssuePlugin, { ReportIssueDialog } from '@ampernic/vitepress-plugin-report-issue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.use(ReportIssuePlugin, {
      repo: 'alt-docs/docs-vitepress',
      origin: 'https://altlinux.space',
      labels: ['documentation'],
      shortcut: 'ctrl-enter',
      locale: 'ru',
    })
  },
  Layout: () => h(DefaultTheme.Layout, null, {
    'layout-top': () => h(ReportIssueDialog),
  }),
}

Плагин цепляет глобальный keydown-обработчик и открывает модалку по совпадению сочетания. Одна и та же опция, переданная пропом на <ReportIssueDialog>, перекрывает конфиг плагина -- удобно, если в отдельной подсекции нужно писать в другой репозиторий.

Через createSharedConfig темы @ampernic/vitepress-theme-alt-docs те же опции пробрасываются полем reportIssue.

Опции

Опция	Тип	По умолчанию	Описание
`repo`	`string`	--	Обязательное. Слаг репозитория `owner/name` на Forgejo/Gitea
`origin`	`string`	`'https://altlinux.space'`	База инстанса Forgejo/Gitea
`labels`	`string[]`	`[]`	Метки, приклеиваемые к issue через query
`shortcut`	`'ctrl-enter' \| 'meta-enter'`	`'ctrl-enter'`	Сочетание открытия. `meta-enter` = Cmd+Enter на macOS
`locale`	`string`	`useData().lang`	Переопределяет язык интерфейса диалога
`fallbackLocale`	`string`	`'en'`	Локаль-фолбэк, если для текущей нет перевода
`messages`	`Partial<Record<string, Partial<Messages>>>`	`{}`	Точечные переводы отдельных строк по локалям

Локализация

Встроены ru и en. Дополнительные локали передаются через messages -- ключи полей смотрите в Messages (все строки, что видит пользователь). Пример добавления немецкого:

app.use(ReportIssuePlugin, {
  repo: 'my-org/my-docs',
  messages: {
    de: {
      title: 'Dokumentationsfehler melden',
      submit: 'Bei Forgejo weiter',
    },
  },
})

Почему URL, а не POST

URL-префилл открывает форму создания issue в UI Forgejo, где пользователь уже авторизован. Не нужен сервисный токен, не нужен настроенный CORS, не нужен свой rate-limit. Если проект дорастёт до headless-подачи (мобильное приложение, embed в iframe), тот же собранный URL можно скормить /api/v1/repos/{owner}/{repo}/issues с персональным токеном.

vitepress-plugin-report-issue ​

Установка ​

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

Опции ​