Руководство 6: дать читателям возможность комментировать

$ опубликовано 2026-11-10 | | обновлено 2026-11-14
Контекст: Настройка репозитория Giscus, комментарии статей и заметок, mapping, общие обсуждения переводов, параметры и устранение ошибок.

Подключите Giscus и выберите связь обсуждений статей, переводов и заметок.


Вывод
слов 1.4k токенов 1.8k

Это руководство 6 из 8. Порядок всех руководств · Справочник настроек.

Anglefeint использует Giscus для комментариев, по умолчанию отключённых. Статьи и заметки включаются отдельно. Комментарии и реакции хранятся в настроенных GitHub Discussions; отдельная база данных статическому блогу не нужна.

Один раз настройте репозиторий и решите, делить ли обсуждения переводов. Изменять шаблон статьи или вставлять script в каждую статью не требуется.

1. Подготовьте репозиторий GitHub и категорию

Откройте страницу настройки Giscus и выполните её проверки:

  1. Выберите свой публичный репозиторий GitHub для комментариев: репозиторий блога или отдельный.
  2. Включите Discussions.
  3. Установите приложение Giscus и предоставьте ему доступ к репозиторию.
  4. Выберите категорию и сохраните созданные данные репозитория и категории.

Страница создаёт script, но теме нужны только значения полей:

Атрибут Giscus Поле темы
data-repo theme.comments.repo, например yourname/your-repository
data-repo-id theme.comments.repoId, ID репозитория, не название
data-category theme.comments.category, настоящее название категории
data-category-id theme.comments.categoryId, ID категории, не название

Не используйте пример ID, URL репозитория или имя пользователя вместо настоящего ID. Категория не обязательно Announcements: укажите выбранное название и соответствующий ID. Не нужны npm-пакет Giscus, GitHub token или пароль.

Это внешний сервис: страница должна подключаться к Giscus и GitHub. Посетителю для комментария нужна авторизация GitHub; можно участвовать и непосредственно в GitHub Discussion. Тема не предоставляет анонимные комментарии. Поведение сервиса определяет официальная документация Giscus.

2. Сначала включите комментарии обычных статей

Объедините с существующим defineThemeConfig({...}) в src/site.config.ts:

theme: {
  comments: {
    enabled: true,
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
    mapping: 'pathname',
    lang: '',
  },
},

Замените аккаунт, репозиторий, категорию и оба ID. В существующих theme/comments меняйте поля с сохранением остальных настроек, не создавайте повторные объекты.

Пример включает комментарии статей и связывает обсуждения по пути URL. /zh/blog/my-first-post/ и /en/blog/my-first-post/ — разные пути и по умолчанию разные обсуждения. shareAcrossLocales по умолчанию false. Если раньше он был включён, восстановите mapping по инструкции ниже: одного примера недостаточно.

Компонент статьи выводится только при включённых комментариях и четырёх заполненных полях репозитория/категории. Без них область может отсутствовать. Заполнители обычно проходят локальную проверку непустоты, но не подтверждают удалённую настройку. Переключателя frontmatter для отдельной статьи нет: comments: false одну статью не отключает.

lang: '' примера следует языку статьи. Настоящий стандарт темы — фиксированный lang: 'en', поэтому для следования странице явно очистите поле. zh соответствует zh-CN, zh-hant — zh-TW, pt-br — pt. Это меняет интерфейс, не переводит комментарии посетителей.

3. Убедитесь в настоящем подключении

Сохраните и откройте статью в локальном dev, найдите область комментариев внизу. Проверьте репозиторий обсуждения, вход, комментарии и реакции. Пустое обсуждение при первом открытии не означает сбой: Giscus может создать его при первом комментарии или реакции, а не сразу при просмотре.

Перед публикацией остановите dev и выполните:

npm run doctor
npm run preview

doctor включает проверки и сборку; после успеха сразу повторять build не нужно. preview показывает локальную сборку, не публикует сайт. Для настоящего сайта нужно повторное размещение. Успешная сборка подтверждает локальную конфигурацию и создание страниц, но не заменяет браузерную проверку прав реального репозитория и связи с сервисом.

Статьи используют loading: 'lazy' по умолчанию. Это режим iframe Giscus, а не ожидание прокрутки перед выводом script: статья выводит асинхронный скрипт Giscus. В отличие от неё, окно заметки загружает клиент после кнопки комментариев.

Типы, значения и примеры всех параметров — в справочнике Giscus. Для существующих комментариев особенно проверьте mapping и ограничения общего обсуждения.

4. Выберите связь статьи с обсуждением

Обычно оставьте pathname. Перед изменением изучите основу сопоставления, особенно если комментарии уже есть:

mapping Основа и ограничения
'pathname' Путь URL без домена; смена пути может выбрать другое обсуждение
'url' Полный URL, поэтому и смена домена может изменить связь
'title' title вкладки; изменение заголовка статьи или сайта может повлиять
'og:title' Заголовок Open Graph страницы
'specific' Фиксированный term; вне общего режима должен быть непустым
'number' Номер существующего discussion из number, не issue; автоматического создания нет

Поиск обсуждения выполняет Giscus, локальной базы комментариев тема не создаёт. strict: '1' уменьшает нечёткие совпадения похожих названий, по умолчанию '0'.

Вне общего режима term и number глобальны для всех комментариев. specific с фиксированным term заставит все использующие его статьи искать одно обсуждение; number тоже указывает один номер. Они не распределяют отдельные обсуждения автоматически.

При включённых комментариях тема проверяет: term для specific непустой после удаления пробелов; number — строка положительного целого, например '42', не число 42, '0' или дробь. Ошибочные параметры останавливают проверку и могут блокировать dev/build.

5. Объедините комментарии переводов одной статьи

Чтобы китайский и английский переводы делили обсуждение, а разные статьи были независимы, сохраните настоящие поля репозитория/категории и объедините mapping так:

theme: {
  comments: {
    // Сохраните enabled: true и свои значения repo, repoId, category и categoryId.
    shareAcrossLocales: true,
    mapping: 'specific',
    term: '',
    number: '',
    strict: '1',
    lang: '',
  },
},

Общий режим требует specific, пустых term и number и строкового strict '1'. Пустой term намеренный: страница подставляет полный slug без языкового каталога, а не общий фиксированный термин.

Например, src/content/blog/zh/my-first-post.md и src/content/blog/en/my-first-post.md используют my-first-post. Вложенные guides/setup и other/setup сохраняют полный путь и остаются разными обсуждениями. Переводам нужен одинаковый slug; сходство заголовков или текста не используется.

При включённых общем режиме и комментариях неправильный mapping, непустые term/number или strict не '1' вызывают явную ошибку. Стандартные маршруты передают slug; собственная страница с BlogPost тоже должна передать действительный articleSlug. Интерфейс определяется lang, текст комментариев не переводится.

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

Что делать с существующими комментариями?

Тема не объединяет, не переносит и не удаляет обсуждения. После включения общего режима выбранное обсуждение может измениться: старые комментарии остаются в GitHub, но не видны через новую связь.

До смены сохраните repo, category, mapping, term, number и strict. Для восстановления задайте shareAcrossLocales: false и верните исходные значения. Простое отключение общего режима с пустым term в specific вызовет ошибку. Если нужна уборка обсуждений, сначала проверьте данные и связи в GitHub: автоматической миграции нет.

6. Комментарии заметок включаются отдельно

Только для заметок заполните ту же группу репозитория/категории и задайте:

theme: {
  fragments: {
    enabled: true,
    comments: { enabled: true },
  },
  comments: {
    enabled: false,
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
  },
},

theme.comments.enabled: false отключает лишь статьи; заметки управляются theme.fragments.comments.enabled. Если статьи тоже нужны, сохраните true; ради заметок менять их mapping не нужно.

Заметки используют фиксированные specific, строгое совпадение и fragment/<id>, не используют mapping, term, number, shareAcrossLocales и фиксированный lang статей. Интерфейс следует странице, переводы с одним ID делят обсуждение. Реакции, цветовая тема, положение поля и другие общие параметры используются совместно. Включённые заметки без четырёх полей репозитория/категории сразу вызывают ошибку конфигурации.

Клиент загружается при первом щелчке комментариев карточки. Закрытие сохраняет экземпляр для повторного открытия и переключения заметок. При ошибке или ожидании примерно 15 секунд предлагается повтор. Подсказка загрузки не подтверждает подключение. Правила публикации, ID и ссылок — в руководстве заметок.

По необходимости: отображение и загрузка

Все поля ниже находятся в theme.comments; обычно достаточно стандартных значений.

Поле По умолчанию в теме Назначение
reactionsEnabled '1' Реакции на основную запись discussion; '0' выключает
inputPosition 'bottom' Положение формы: 'top'/'bottom'
theme 'dark' Цветовой идентификатор Giscus из его страницы настройки; не переключает тему блога
strict '0' Строгое совпадение статьи; общий режим и заметки принудительно '1'
emitMetadata '0' Отправка метаданных обсуждения родительской странице, не метаданные публикации; для готовности заметок включается принудительно
lang 'en' Фиксированный язык интерфейса статей; '' следует странице, заметки всегда следуют странице
loading 'lazy' iframe статьи 'lazy'/'eager'; открытое окно заметок использует eager
crossorigin 'anonymous' Атрибут script: 'anonymous'/'use-credentials'; обычно менять не нужно, GitHub-вход не заменяет

enabled и shareAcrossLocales — boolean true/false, а strict, reactionsEnabled и emitMetadata — строки '0'/'1'. Не смешивайте типы из-за похожего вида.

Если комментариев нет или связь неправильная

Симптом Порядок проверки
Совсем нет области статьи Включены ли статьи и заполнены ли четыре поля; переключатель заметок на статьи не влияет
Включение заметок сразу даёт ошибку Заполнены ли все поля репозитория/категории, а не только переключатель
Удалённая ошибка или бесконечная загрузка Настоящие ID, публичность, Discussions, доступ приложения, соответствующая категория, сеть и блокировщики
Разные статьи показывают одно обсуждение Глобальный term/number, правильность общего режима и фактическое совпадение Giscus
Переводы не объединены shareAcrossLocales, одинаковые slug и все ограничения общего mapping
После смены mapping комментарии «исчезли» Проверьте старое обсуждение в GitHub; не меняйте многократно заголовки/ID и не удаляйте обсуждения для восстановления
Интерфейс всегда английский Стандартный lang en; для страницы задайте ''. Комментарии посетителей это не переводит
Локально изменилось, онлайн нет Повторные сборка/размещение, не используется ли старая конфигурация

Статьи отключаются через theme.comments.enabled: false, заметки — через theme.fragments.comments.enabled: false. Это убирает соответствующий вход/встраивание, не удаляя GitHub Discussions. Обновление темы не мигрирует обсуждения: сохраните mapping до обновления и проверьте связи после. Инструкция — в руководстве установки.

Навигация по руководствам и настройкам

Назад: настройка страниц и функций · Далее: другие языки · Все восемь руководств.

Связанные настройки: Giscus и общие обсуждения, переключатель комментариев заметок. Полные пути, значения и ограничения — в общем справочнике.