Plugin de Threads

El plugin @docmd/plugin-threads permite comentarios colaborativos en línea y anotaciones de texto en las páginas de documentación. Los resaltados y los hilos de discusión se almacenan de forma nativa dentro de los archivos Markdown de origen mediante bloques contenedores personalizados (::: threads), sin necesidad de bases de datos externas.

Autor original: @svallory

Instalación y configuración

Instale el plugin mediante la CLI:

npx @docmd/core add threads

Habilite la configuración de hilos en docmd.config.json:

Requisito de servidor de desarrollo en vivo

La interfaz de comentarios, las herramientas de resaltado y la persistencia de cambios en Markdown requieren un servidor de desarrollo activo (docmd dev) con conexión WebSocket RPC funcional.

Debido a que Threads declara requiresLiveServer: true:

• En desarrollo (docmd dev): La pestaña deslizante, las tarjetas de vista previa en línea, los modales de selección y la barra lateral de hilos están completamente activos y operativos.
• Compilaciones estáticas de producción (docmd build): Los scripts y hojas de estilo del cliente se omiten automáticamente para garantizar que los sitios públicos se mantengan ultrarrápidos, sin sobrecarga y libres de intentos fallidos de conexión WebSocket. Cualquier sintaxis de hilos en Markdown (::: threads y ==texto=={t-...}) sigue procesándose correctamente sin advertencias.
• Anulación manual: Si desea expresamente empaquetar los activos de Threads en compilaciones estáticas, configure "devOnly": false en plugins.threads.

Ejemplo de configuración global

{
  "plugins": {
    "threads": {
      "sidebar": true,
      "devOnly": true
    }
  }
}

Flujo de trabajo

1. Selección de texto: Seleccione un fragmento de texto durante el desarrollo en vivo local (npx @docmd/core dev).
2. Modal de comentario: Ingrese sus observaciones en la ventana emergente.
3. Inyección del ancla: El texto seleccionado se resalta con un identificador de hilo (==texto resaltado=={t-a1b2c3d4}).
4. Persistencia en Markdown: La estructura del hilo se anexa al final del archivo Markdown en un bloque ::: threads.
5. Sincronización con Git: El historial de discusión se almacena en el control de versiones junto a los cambios del documento.

Vista previa interactiva

El texto con discusiones asociadas recibe resaltados de color en línea. Las tarjetas de discusión se muestran debajo:

Los resaltados adicionales alternan automáticamente entre paletas de color distintivas:

Las discusiones resueltas se muestran atenuadas:

Una pestaña deslizante anclada a la derecha 2 reposa en el borde de la pantalla mostrando el número de hilos pendientes. Al pasar el cursor sobre cualquier texto resaltado, aparece una tarjeta de vista previa integrada directamente en el contenido, mientras que al pulsar la pestaña se despliega el panel lateral de discusión. Los hilos se conservan permanentemente entre aperturas y cierres del panel sin necesidad de recargar la página.

Formato de almacenamiento en Markdown

Los hilos se guardan dentro de los archivos de origen utilizando sintaxis de bloques contenedores:

# Visión general del motor

La arquitectura central incluye ==texto resaltado=={t-a1b2c3d4} con un hilo adjunto.

::: threads
  ::: thread t-a1b2c3d4
    ::: comment c-e5f6a7b8 "Alice" "2026-04-09"
      Este texto requiere mayor detalle técnico.
    :::
    ::: comment c-d9e0f1a2 "Bob" "2026-04-09" reply-to c-e5f6a7b8
      Actualizado con especificaciones adicionales.

      ::: reactions
        - 👍 Alice
      :::
    :::
  :::
:::

Características principales

• Selección de texto: Resalte cualquier fragmento de texto para anclar un nuevo hilo.
• Respuestas anidadas: Conversaciones en árbol con respuestas organizadas.
• Reacciones con emojis: Contadores de reacciones asociados a comentarios.
• Estado de resolución: Marque hilos como resueltos con atribución de autoría.
• Identidad de autor: Las credenciales locales de Git determinan el avatar y perfil automáticamente.

API de acciones RPC

El plugin de Threads expone puntos de enlace WebSocket RPC invocables con docmd.call():

Almacenamiento de perfiles de autor

Los perfiles de los autores se guardan en caché en <docsRoot>/.threads/authors.json:

{
  "alice@example.com": {
    "name": "Alice",
    "avatarUrl": "https://gravatar.com/avatar/..."
  }
}