Corregir enlaces rotos

jamdesk fix es el complemento de corrección automática de jamdesk broken-links. Lee las mismas advertencias de enlaces rotos y reescribe cualquier archivo donde el destino correcto se pueda determinar sin ambigüedad. Los casos ambiguos se marcan para revisión manual y se dejan sin modificar.

Corrige dos tipos de enlaces internos rotos:

• Anclas mal escritas — un fragmento que es un error ortográfico evidente de un encabezado real en la página de destino (por ejemplo, #instalation → #installation)
• Desfase de anclas entre idiomas — una página traducida cambió el nombre de sus encabezados, pero los enlaces de esa versión en el idioma siguen apuntando al fragmento en inglés antiguo (por ejemplo, /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia)

Paso 1: Encontrar enlaces rotos

Ejecuta jamdesk broken-links para ver qué se debe corregir:

jamdesk broken-links

Revisa la salida. jamdesk fix se enfoca en las advertencias donde es posible hacer coincidir un ancla probablemente correcta con un encabezado real.

Paso 2: Previsualizar las correcciones

Ejecuta con --dry-run para ver exactamente qué cambiaría antes de tocar ningún archivo:

jamdesk fix --dry-run

Ejemplo de salida:

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

Revisa cada corrección planificada. Si un cambio no se ve bien, corrige ese enlace a mano en lugar de aplicarlo. jamdesk fix solo reescribe enlaces que puede resolver sin ambigüedad.

Paso 3: Aplicar las correcciones

Ejecuta sin --dry-run para aplicar los cambios. Se te pedirá que confirmes:

jamdesk fix

Apply 1 fix(es) to local files? (y/N)

Presiona y para escribir los cambios. Para omitir la confirmación en CI o en scripts, usa -y:

jamdesk fix -y

Después de aplicar los cambios, el comando imprime:

Fixed 1 file(s); 0 warning(s) left for manual review.

Si el destino de una advertencia es ambiguo, jamdesk fix lo deja sin modificar para que lo resuelvas a mano.

Paso 4: Revisar el diff y hacer commit

Revisa los cambios antes de hacer commit:

git diff

Verifica que cada enlace reescrito apunte adonde esperas. Luego haz commit:

git add -A
git commit -m "fix(docs): auto-fix broken internal links"

Uso con un agente de IA

jamdesk fix --json imprime el plan de corrección como un único documento JSON para un agente de programación como Claude Code. No escribe archivos ni hace preguntas. El agente hace las ediciones. Requiere la CLI 1.1.229 o posterior.

jamdesk fix --json

Ejemplo de salida (recortada):

{
  "version": 1,
  "fixes": [
    {
      "type": "broken_link",
      "file": "fr/ai/overview.mdx",
      "line": 9,
      "oldText": "/fr/ai/selectors#ai-strategies",
      "newText": "/fr/ai/selectors#stratégies-ia",
      "resolvedBy": "deterministic"
    },
    {
      "type": "description",
      "file": "setup.mdx",
      "text": "How to set up the CLI.",
      "resolvedBy": "ai"
    }
  ],
  "unfixable": [
    {
      "type": "broken_link",
      "file": "quickstart.mdx",
      "line": 4,
      "link": "/missing",
      "reason": "points at a page that doesn't exist; create it or fix the link"
    }
  ],
  "notes": []
}

El documento tiene tres listas:

• fixes: las ediciones que hay que hacer. En un broken_link, reemplaza oldText por newText en esa línea. Una description es una sugerencia de IA para el frontmatter de la página, así que el agente debe mostrártela antes de escribirla.
• unfixable: problemas que hay que corregir a mano, cada uno con un motivo.
• notes: mensajes de la ejecución, por ejemplo cuando se omitieron las correcciones con IA.

Si la ejecución falla, la salida es {"version": 1, "error": "..."} y el comando termina con el código 1.

Para empezar, pídele algo así a tu agente: "Ejecuta jamdesk fix --json, aplica las correcciones de enlaces y muéstrame las descripciones antes de añadirlas."

Opciones

¿Qué sigue?