Справочник настроек: Giscus и общие обсуждения переводов
Подключение, mapping статей, переопределения заметок и язык интерфейса.
На этой странице
Для первой настройки прочитайте комментарии читателей с подготовкой репозитория и получением параметров. Файл — в установке, остальные модули — в общем справочнике.
Общие настройки — theme.comments в src/site.config.ts; стандартно отключены. Ниже стандарты пакета, не подключённый личный репозиторий demo. ID и repo выводятся в страницу и публичны; не помещайте GitHub access token или секреты.
Различайте два переключателя
| Путь | Тип / стандарт | Состояние, действие и ограничения | Пример |
|---|---|---|---|
| theme.comments.enabled | boolean / false | Условно: статьи, не кнопки заметок. При недостающих параметрах область может не выводиться; это не проверка удалённого сервиса | theme: { comments: { enabled: true } } |
| theme.fragments.comments.enabled | boolean / false | Условно: список заметок, нужен theme.fragments.enabled true. Независим от статей; отсутствие подключения вызывает ошибку генерации заметок | theme: { fragments: { enabled: true, comments: { enabled: true } } } |
Нет comments: false frontmatter отдельной статьи или заметки. Превью главной не имеет кнопки комментариев. Остальное — в Fragments.
Все поля theme.comments
Префикс всех строк — theme.comments., например theme.comments.repo. В частичном вводе поля необязательны и дополняются стандартами темы. Строковые флаги сохраняйте в кавычках, не boolean/число.
Все условны: статьям нужны включение и условия вывода; заметки используют только часть, остальные переопределяют/игнорируют. Общего правила восстановления стандартов пустой строкой нет. Помимо явных mapping-проверок, правильный тип/непустота не доказывают удалённую конфигурацию Giscus.
Репозиторий и категория
| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
|---|---|---|---|---|
repo |
string | "" |
GitHub owner/repo. Статья требует truthy, заметка дополнительно непустое после trim. Не добавляйте крайние пробелы; удалённые права не проверяются | "your-account/blog-discussions" |
repoId |
string | "" |
ID из Giscus, не имя repo, номер или access token; общий | "YOUR_REPOSITORY_ID" |
category |
string | "" |
Настоящая категория Giscus в паре с categoryId, не тег статьи | "Announcements" |
categoryId |
string | "" |
ID, не имя категории. Статьи требуют truthy, заметки trim-непустоту; подлинность не проверяется | "YOUR_CATEGORY_ID" |
Mapping статей и строгое совпадение
| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
|---|---|---|---|---|
mapping |
‘pathname’ | ‘url’ | ‘title’ | ‘og:title’ | ‘specific’ | ‘number’ | "pathname" |
Связь статьи/обсуждения, значения ниже. Общему режиму нужен specific; заметки поле не используют | "pathname" |
term |
string | "" |
specific необщих статей: непустой после trim, общий фиксированный для сайта. В общем режиме пустой, затем slug статьи; в остальных не передаётся | "my-fixed-discussion" |
number |
string | "" |
number необщих статей: после trim строка положительного безопасного целого без начальных нулей, плюса или дроби. В общем режиме пустой; в других не передаётся | "42" |
strict |
‘0’ | ‘1’ | "0" |
Строковый, не boolean. Общий режим требует 1, заметки принудительно 1. Не объединяет обсуждения с одинаковым заголовком | "1" |
Вид, язык и загрузка
| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
|---|---|---|---|---|
reactionsEnabled |
‘0’ | ‘1’ | "1" |
Реакции основной записи обсуждения, общие; не отключение всех действий | "1" |
emitMetadata |
‘0’ | ‘1’ | "0" |
Метаданные Giscus родительскому окну. Статьи передают настройку без автоматической статистики; заметки принудительно 1 для готовности/смены | "0" |
inputPosition |
‘top’ | ‘bottom’ | "bottom" |
Форма над/под списком, общая; не положение всей области на странице | "top" |
theme |
string | "dark" |
Тема iframe Giscus, не Matrix/Cyber/Hacker/AI. Общая, поддержка имён сервисом не проверяется, автоматической смены по сцене нет | "dark" |
lang |
string | "en" |
Язык интерфейса статей: непустой передаётся, пустой маппится из страницы. Заметки всегда следуют странице; текст комментариев не переводится | "" |
loading |
‘lazy’ | ‘eager’ | "lazy" |
Подсказка iframe статей, не задержка вывода client.js. Заметки eager после кнопки | "lazy" |
crossorigin |
‘anonymous’ | ‘use-credentials’ | "anonymous" |
Атрибут script клиента, общий; не логин repo, token или исправление разрешений | "anonymous" |
theme.comments.shareAcrossLocales: общие обсуждения переводов
- Тип / стандарт: необязательный boolean / false.
- Состояние и действие: условно при комментариях статей; одинаковый полный slug разных языков связывает с одним обсуждением, разные slug независимы.
- Ограничения: mapping ‘specific’, term/number пусты после trim, strict строка ‘1’. Иначе ошибка, одного boolean недостаточно. При отключённых статьях эти ограничения пропускаются, но подключение заметок проверяется отдельно.
- Пример: общий фрагмент ниже. Не переводит, не объединяет старые обсуждения и не меняет связь заметок.
| Файл статьи | Реальный term общего режима |
|---|---|
| src/content/blog/zh/my-first-post.md | my-first-post |
| src/content/blog/en/my-first-post.md | my-first-post |
| src/content/blog/zh/guides/setup.md | guides/setup |
| src/content/blog/en/other/setup.md | other/setup |
Полный slug без языка, не заголовок, canonicalTopic или сходство текста. Стандартный маршрут передаёт articleSlug. Собственный BlogPost тоже требует непустой полный slug без крайних пробелов, пустых сегментов и . / ... Это параметр компонента, не site.config.
Несколько сайтов с одинаковым slug в одном repo/category могут попасть в одно обсуждение: домен не создаёт отдельную базу. С сохранением пути смена заголовка не меняет term; смена slug/repo/category/стратегии может изменить обсуждение.
Значения mapping
| Значение | Основа Giscus | Ограничение и пример |
|---|---|---|
| pathname | Путь URL | Стандарт; языковые пути обычно различаются, смена пути меняет связь |
| url | Полный URL | Домен/адрес влияют |
| title | title документа | Заголовок статьи/сайта, не только h1 текста |
| og:title | Open Graph title | Существующие метаданные, не заголовок внутри theme.comments |
| specific | Заданный term | Необщий — фиксированный всего сайта, общий — slug каждой статьи |
| number | Существующий номер Discussion | Общий фиксированный номер строкой ‘42’, не issue; не создаётся автоматически |
Поиск/создание выполняет Giscus. При отсутствии обсуждение может создаться первым комментарием/реакцией, не обязательно просмотром. Нужны публичный repo, Discussions и приложение; см. руководство и Giscus. Локальной базы нет.
При strict ‘1’ Giscus использует хэш заголовка в тексте обсуждения, не локальное сравнение темы. Старым обсуждениям может понадобиться маркер: строгое совпадение. Общий режим/смена mapping не мигрируют, не объединяют и не удаляют старое. Комментарии могут остаться в GitHub вне новой связи; сначала определите соответствие старого обсуждения новому term.
Необщий specific с одним term направляет все статьи к одному обсуждению; number тоже фиксирован для сайта. Это не автоматический ID каждой статьи. Нерелевантные term/number не отправляются, но оба всё равно проходят trim: не заменяйте строки null/числом.
Примеры для объединения
Добавьте в существующий defineThemeConfig({…}) src/site.config.ts, сохранив import/export и личные настройки без второго theme. Четыре значения подключения получите своим Giscus: заполнители показывают структуру, не пригодны для онлайн-проверки.
Отдельные обсуждения статей по пути
theme: {
comments: {
enabled: true,
repo: 'your-account/blog-discussions',
repoId: 'YOUR_REPOSITORY_ID',
category: 'Announcements',
categoryId: 'YOUR_CATEGORY_ID',
shareAcrossLocales: false,
mapping: 'pathname',
lang: '',
},
},
Общее обсуждение переводов статьи
Сохраните подключение и объедините mapping:
theme: {
comments: {
enabled: true,
shareAcrossLocales: true,
mapping: 'specific',
term: '',
number: '',
strict: '1',
lang: '',
},
},
Реальный lang по умолчанию ‘en’, не следование странице. Пустая строка выше явно включает языковой mapping: zh→zh-CN, zh-hant→zh-TW, pt-br→pt, остальные напрямую. Поддержку определяет Giscus. Меняется интерфейс, не идентичность и не опубликованный текст. theme.comments глобален, не копируйте его в i18n.locales.
Строка theme напрямую передаётся Giscus, например ‘dark’/‘light’. Доступные темы и URL custom CSS определяет сервис, внешняя AI-панель не меняется. См. темы Giscus; пакет не проверяет содержимое/доступность CSS.
Какие общие поля используют заметки?
| Общее поле | Поведение заметок |
|---|---|
| repo / repoId / category / categoryId | Общие, непустые после trim; передаются исходные, не добавляйте крайние пробелы; удалённые права не проверяются |
| theme / reactionsEnabled / inputPosition / crossorigin | Общие исходные значения |
| enabled | Игнорирует статьи, использует theme.fragments.comments.enabled |
| shareAcrossLocales | Не используется, одинаковый стабильный ID уже общий |
| mapping / term / number | specific, term fragment/<ID>, number не отправляется |
| strict / emitMetadata | Фиксированные ‘1’ / ‘1’ |
| lang | Игнорируется, mapping языка страницы заметок |
| loading | eager, но клиент после первого щелчка |
Пример только заметок без статей:
theme: {
comments: {
enabled: false,
repo: 'your-account/blog-discussions',
repoId: 'YOUR_REPOSITORY_ID',
category: 'Announcements',
categoryId: 'YOUR_CATEGORY_ID',
},
fragments: { enabled: true, comments: { enabled: true } },
},
Одинаковые ID языков делят fragment/<ID>, это другая система, чем slug статей. Не меняйте ID ради сортировки/пагинации. Первое открытие загружает окно, закрытие сохраняет iframe, смена посылает конфигурацию Giscus. Примерно через 15 секунд без действительного результата ошибка/повтор. Публичных timeout/preload нет. Если статьи тоже включены, их mapping проверяется даже при настройке только заметок.
Тексты самой страницы
Необязательные string в i18n.locales.<locale>.messages, стандарт — встроенный язык/откат. Примеры внутри соответствующего объекта. Меняют внешние labels, не кнопки iframe. Ниже настоящие стандарты упрощённого китайского/английского.
| Относительное поле | Стандарт упрощённого китайского / английского | Состояние, действие и ограничения | Пример |
|---|---|---|---|
blog.comments |
评论 / Comments | Условно: доступное имя области статьи, не дополнительный видимый заголовок | "Обсуждение статьи" |
fragments.comments |
评论 / Comments | Условно: кнопка и заголовок окна заметок | "Обсудить" |
fragments.close |
关闭 / Close | Условно: закрытие окна, также доступное имя окна главной | "Закрыть окно" |
fragments.loading |
正在加载评论… / Loading comments… | Условно: загрузка заметок | "Загрузка обсуждения…" |
fragments.error |
评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | Условно: ошибка заметок | "Обсуждение временно недоступно." |
fragments.retry |
重试 / Retry | Условно: повтор после ошибки | "Перезагрузить" |
Остальные тексты — статьи и Fragments. Они не задают язык iframe, который следует правилам lang выше.
Границы загрузки и проверок
Статья выводит асинхронный client.js. loading ‘lazy’ передаётся iframe, не означает ожидание прокрутки для script. Заметки сначала выводят шаблон и вставляют клиент после кнопки; eager относится к iframe после щелчка. Giscus различает эти уровни.
Локальный код проверяет mapping статей и обязательные поля заметок, не GitHub-вход, права приложения, публичность, категории, сеть или сервис. Пустое подключение статьи может не рендериться; строка из пробелов может пройти её условие вывода, но неверна. Заметки проверяют непустоту строже, не подлинность ID.
Все theme.comments потребляются, но не все для заметок: переопределения выше. Нет публичных индивидуальных переключателей, self-host адреса, сортировки, admin token или локальной базы. Клиент фиксирован https://giscus.app/client.js. Настройки repo Giscus не новые поля site.config.
После изменения пересоберите и разместите. Успех сборки не подтверждает настоящий сервис. Миграция/права выполняются на GitHub/Giscus, не автоматически при сохранении site.config. Назад к общему справочнику.