Руководство 6: дать читателям возможность комментировать
Подключите Giscus и выберите связь обсуждений статей, переводов и заметок.
На этой странице
Это руководство 6 из 8. Порядок всех руководств · Справочник настроек.
Anglefeint использует Giscus для комментариев, по умолчанию отключённых. Статьи и заметки включаются отдельно. Комментарии и реакции хранятся в настроенных GitHub Discussions; отдельная база данных статическому блогу не нужна.
Один раз настройте репозиторий и решите, делить ли обсуждения переводов. Изменять шаблон статьи или вставлять script в каждую статью не требуется.
1. Подготовьте репозиторий GitHub и категорию
Откройте страницу настройки Giscus и выполните её проверки:
- Выберите свой публичный репозиторий GitHub для комментариев: репозиторий блога или отдельный.
- Включите Discussions.
- Установите приложение Giscus и предоставьте ему доступ к репозиторию.
- Выберите категорию и сохраните созданные данные репозитория и категории.
Страница создаёт 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 и общие обсуждения, переключатель комментариев заметок. Полные пути, значения и ограничения — в общем справочнике.