Referencia de configuración: Giscus y discusiones multilingües

$ publicado 2026-11-13 | | actualizado 2026-11-14
Contexto: Tipos, valores y restricciones de Giscus y la compartición de discusiones entre idiomas.

Conexión, asociación, presentación y comentarios de fragments


Salida
palabras 1.8k tokens 2.3k

Para empezar, lee permitir comentarios para preparar repositorio y obtener parámetros. Consulta el archivo en instalación y otros módulos en el índice.

Los ajustes compartidos están en theme.comments de src/site.config.ts. Apagados por defecto. Los valores son del paquete, no del repositorio personal conectado al demo. IDs y parámetros son información pública incluida en páginas. No introduzcas tokens GitHub ni secretos.

Distinguir los dos controles

Ruta Tipo / predeterminado Estado, función y límites Ejemplo
theme.comments.enabled boolean / false Condicional: solo entradas, no botones de fragments. Faltar conexión puede ocultar zona; renderizar no valida servicio remoto theme: { comments: { enabled: true } }
theme.fragments.comments.enabled boolean / false Condicional: lista de fragments, requiere theme.fragments.enabled. Independiente de artículos. Faltar conexión requerida causa error al generar páginas theme: { fragments: { enabled: true, comments: { enabled: true } } }

No hay frontmatter comments: false por artículo. Tampoco control individual por fragment; las vistas de inicio no muestran comentarios. Consulta Fragments.

Todos los campos theme.comments

Todos llevan prefijo theme.comments.; por ejemplo repo es theme.comments.repo. Pueden omitirse en entradas parciales y completarse con defaults. Los indicadores string deben ir entre comillas, no booleanos/números.

Son condicionales: comentarios de artículos activos y elegibles para salida. Fragments usa solo parte y fuerza/ignora el resto. Vacío no restaura defaults universalmente: revisa cada fila. Tipo correcto y no vacío no prueban validez Giscus remota, aparte de restricciones explícitas de mapping.

Repositorio y categoría

Campo Tipo Predeterminado Función, condiciones y límites Ejemplo
repo string "" GitHub propietario/repositorio. Artículos exigen valor truthy; fragments no vacío tras trim. Evita espacios; no comprueba permisos remotos "your-account/blog-discussions"
repoId string "" ID de repositorio Giscus, no nombre, secuencia numérica ni token. Compartido por artículos/fragments "YOUR_REPOSITORY_ID"
category string "" Nombre de categoría proporcionado por Giscus con su categoryId; no etiqueta de artículo "Announcements"
categoryId string "" ID de categoría Giscus, no nombre. Artículos exigen truthy, fragments no vacío tras trim; sin validación remota "YOUR_CATEGORY_ID"

Asociación de artículos y coincidencia estricta

Campo Tipo Predeterminado Función, condiciones y límites Ejemplo
mapping ‘pathname’ | ‘url’ | ‘title’ | ‘og:title’ | ‘specific’ | ‘number’ "pathname" Asociación de artículos, valores explicados abajo. Compartir exige specific. Fragments ignora "pathname"
term string "" Para artículos no compartidos en specific; no vacío tras trim. Fijo global. Compartir exige vacío y usa slug al renderizar. No se envía en otros modos "my-fixed-discussion"
number string "" Modo number no compartido: string de entero seguro positivo tras trim, sin ceros iniciales, signo más ni decimales. Compartir exige vacío. No se envía en otros modos "42"
strict ‘0’ | ‘1’ "0" Indicador estricto string, no booleano. Compartir exige 1; fragments fuerza 1. No combina discusiones de títulos iguales "1"

Apariencia, idioma y carga

Campo Tipo Predeterminado Función, condiciones y límites Ejemplo
reactionsEnabled ‘0’ | ‘1’ "1" Reacciones de la publicación de discusión, compartido. No desactiva todas las acciones de comentario "1"
emitMetadata ‘0’ | ‘1’ "0" Solicita metadatos de discusión al padre. Artículos lo pasan sin mostrar conteos automáticamente. Fragments fuerza 1 para carga/cambios "0"
inputPosition ‘top’ | ‘bottom’ "bottom" Entrada encima/debajo, compartido; no mueve toda la zona "top"
theme string "dark" Tema de iframe Giscus, no Matrix/Cyber/Hacker/AI. Compartido, sin validar nombres ni seguir escena automáticamente "dark"
lang string "en" Idioma de interfaz de artículos. No vacío se pasa directo; vacío se mapea desde página. Fragments ignora y sigue página. No traduce respuestas ""
loading ‘lazy’ | ‘eager’ "lazy" Indicación iframe de artículos, no toda inserción client.js. Fragments fuerza eager, pero inserta tras clic "lazy"
crossorigin ‘anonymous’ | ‘use-credentials’ "anonymous" crossorigin del script compartido; no credenciales de repositorio, token ni arreglo de permisos "anonymous"

theme.comments.shareAcrossLocales: compartir discusiones de artículos

  • Tipo / predeterminado: boolean opcional / false.
  • Estado y función: condicional a comentarios activos. Versiones de mismo slug completo comparten discusión; slugs distintos quedan separados.
  • Límites: exige mapping ‘specific’, term/number vacíos tras trim y strict string ‘1’. Si no, error; cambiar solo booleano no basta. Se omiten estas restricciones al apagar artículos, pero sigue validación de conexión de fragments.
  • Ejemplo: ajustes compartidos abajo. No traduce comentarios, combina discusiones ni altera asociación de fragments.
Archivo de artículo term compartido real
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

Usa slug completo sin directorio de idioma, no título, canonicalTopic ni cuerpo. Las rutas estándar aportan articleSlug. BlogPost personalizado también necesita slug completo no vacío, sin espacios exteriores, segmentos vacíos ni . / … Es un prop, no campo site.config.

Varios sitios con mismo repositorio, categoría y slug pueden llegar a la misma discusión. El dominio no aísla base de datos. Mantener ruta hace que cambiar título no altere term. Cambiar slug, repositorio, categoría o mapping puede seleccionar otra discusión.

Significado de mapping

Valor Giscus compara Límites y ejemplos
pathname Ruta URL Predeterminado; idiomas suelen tener rutas distintas. Cambiar rutas puede cambiar asociación
url URL completa Cambiar dominio/dirección puede cambiar asociación
title Título de documento Cambiar título de artículo/sitio puede cambiarla; no solo h1
og:title Título Open Graph Lee metadatos existentes; theme.comments no define título
specific term especificado Fijo global sin compartir; generado del slug individual al compartir
number Número Discussion existente Número global fijo como string ‘42’; no issue ni crea discusión automáticamente

Giscus resuelve coincidencia/creación. Una discusión ausente puede crearse con primer comentario/reacción, no necesariamente al abrir. Repositorio público, Discussions y aplicación Giscus obligatorios; consulta tutorial y configuración oficial. El tema no tiene base local.

Con strict ‘1’, Giscus usa hash de título en cuerpos, no comparación local del tema. Las existentes pueden necesitar marcadores; consulta coincidencia estricta. Cambiar mapping/compartición no migra, combina ni borra. Pueden seguir en GitHub y desaparecer de la nueva asociación. Identifica discusiones y terms antes de migrar.

Sin compartir, specific con term fijo dirige todos los artículos a una misma discusión; number también es global. No asignan IDs por entrada. Los valores no pertinentes no se envían, pero ambas strings se recortan siempre: no uses null ni números.

Ejemplos para combinar

Combina en defineThemeConfig({…}) de src/site.config.ts y conserva imports, exports y ajustes sin duplicar theme. Obtén los cuatro datos de tu Giscus; los ejemplos no validan una conexión real.

Separar artículos por ruta

theme: {
  comments: {
    enabled: true,
    repo: 'your-account/blog-discussions',
    repoId: 'YOUR_REPOSITORY_ID',
    category: 'Announcements',
    categoryId: 'YOUR_CATEGORY_ID',
    shareAcrossLocales: false,
    mapping: 'pathname',
    lang: '',
  },
},

Compartir discusión entre traducciones

Conserva tus datos y combina estos ajustes:

theme: {
  comments: {
    enabled: true,
    shareAcrossLocales: true,
    mapping: 'specific',
    term: '',
    number: '',
    strict: '1',
    lang: '',
  },
},

lang predeterminado es ‘en’, no sigue página. El ejemplo lo vacía para mapear: zh → zh-CN, zh-hant → zh-TW, pt-br → pt; otros pasan directamente. Giscus decide idiomas soportados. Cambiar idioma no cambia identidad ni texto publicado. theme.comments es global, no se duplica bajo i18n.locales.

La string theme pasa a Giscus; valores habituales ‘dark’/‘light’. Giscus gestiona temas y URLs CSS, sin cambiar panel IA exterior. Consulta temas oficiales. El paquete no valida CSS personalizado ni accesibilidad.

Qué ajustes comparten los fragments

Campo compartido Conducta real en fragments
repo / repoId / category / categoryId Compartido. Los cuatro no vacíos tras trim. Se pasan originales: evita espacios exteriores. Sin comprobar permisos remotos
theme / reactionsEnabled / inputPosition / crossorigin Usa valores compartidos
enabled Ignora control de artículos; usa theme.fragments.comments.enabled
shareAcrossLocales Sin uso: mismo ID estable ya vincula discusión
mapping / term / number Fuerza specific, term fragment/<ID> y no envía number
strict / emitMetadata Fuerza ‘1’ / ‘1’
lang Ignora lang compartido y mapea idioma actual
loading Fuerza eager; inserta cliente en primer clic de comentarios

Por ejemplo, activa solo fragments y desactiva artículos:

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 } },
},

IDs iguales entre idiomas comparten fragment/<ID>, independientemente de slugs de artículos. No cambies IDs estables para reordenar/paginar. El diálogo carga al primer clic y conserva iframe al cerrar; cambiar tarjeta envía configuración Giscus. Unos 15 segundos sin respuesta válida muestran fallo/reintento. No hay timeout ni precarga públicos. Activar artículos valida su mapping aunque tu intención principal sea comentar fragments.

Textos propios de la página

Estas strings opcionales están bajo i18n.locales.<locale>.messages con textos integrados/respaldo. Pon ejemplos en su objeto. Cambian etiquetas exteriores, no botones del iframe. Solo se muestran chino simplificado / inglés.

Campo relativo Predeterminado chino simplificado / inglés Estado, función y límites Ejemplo
blog.comments 评论 / Comments Condicional: nombre accesible de zona de artículos, no otro título visible "Debate de la entrada"
fragments.comments 评论 / Comments Condicional: botón y título de diálogo de fragments "Participar en el debate"
fragments.close 关闭 / Close Condicional: cierre de diálogo y nombre accesible del cierre de inicio "Cerrar ventana"
fragments.loading 正在加载评论… / Loading comments… Condicional: carga de comentarios de fragments "Cargando debate…"
fragments.error 评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. Condicional: fallo de comentarios de fragments "El debate no está disponible temporalmente."
fragments.retry 重试 / Retry Condicional: reintento tras fallo de fragments "Volver a cargar"

Otros textos están en artículos y Fragments. No eligen idioma iframe; lo hace lang.

Límites de carga y validación

Artículos emiten client.js asíncrono; loading: ‘lazy’ va al iframe, sin esperar scroll para insertar script. Fragments emite plantilla e inserta cliente al clicar; eager describe iframe posterior al clic. Carga oficial distingue capas.

Las comprobaciones locales validan mapping de artículos y campos requeridos de fragments, no login, autorización, visibilidad, categoría, red ni disponibilidad. Campos vacíos de artículos pueden suprimir zona. Solo espacios pueden superar condiciones de salida, pero no son configuración válida. Fragments comprueba más estrictamente vacío, sin validar IDs remotamente.

Todos los campos tienen consumidores, pero no todos se aplican a fragments; arriba se detallan sustituciones. No hay control individual, servicio propio, orden, token administrador ni base local. El cliente está fijado a https://giscus.app/client.js. Configurar Giscus no crea campos adicionales.

Recompila/despliega tras cambios. Compilar no valida el servicio real. Gestiona migración y permisos en GitHub/Giscus, no solo guardando site.config. Vuelve al índice.