Справочник настроек: Giscus и общие обсуждения переводов

$ опубликовано 2026-11-13 | | обновлено 2026-11-14
Контекст: Все поля Giscus, типы и стандарты, ограничения общего обсуждения, совместное использование настроек заметками и границы проверок.

Подключение, mapping статей, переопределения заметок и язык интерфейса.


Вывод
слов 1.6k токенов 2.1k

Для первой настройки прочитайте комментарии читателей с подготовкой репозитория и получением параметров. Файл — в установке, остальные модули — в общем справочнике.

Общие настройки — 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. Назад к общему справочнику.