Inicia el servidor de desarrollo local con recarga en caliente. Características: Validación automática al iniciar (esquema de docs.json, sintaxis MDX y specs de OpenAPI referenciadas; una spec inválida detiene el servidor para que la detectes antes de desplegar) Recarga en caliente al cambiar archivos MDX Reconstrucción automática de la navegación al cambiar docs.json CSS personalizado (style.css) recargado al actualizar el navegador Funcionalidad de búsqueda completa Todos los temas y componentes disponibles Opciones: | Flag | Descripción | |------|-------------| | -p, --port | Puerto en el que ejecutarlo (por defecto: 3000) | | -v, --verbose | Habilitar salida detallada |

Crea un nuevo proyecto de documentación. Esto crea un nuevo proyecto con: Archivo de configuración docs.json Páginas MDX de ejemplo Estructura de carpetas recomendada

Inicia sesión en Jamdesk desde tu navegador. Es necesario antes de desplegar. Abre el dashboard de Jamdesk en tu navegador para la autenticación. Las credenciales se almacenan localmente en ~/.jamdeskrc.

Valida tu configuración de docs.json, la sintaxis MDX y las specs de OpenAPI. Comprueba: Sintaxis JSON válida en docs.json Campos obligatorios (name, navigation) Valores de tema válidos Errores de sintaxis MDX (por ejemplo, caracteres < sin escapar) Validación de specs de OpenAPI (si está configurado) Cumplimiento del esquema Opciones: | Flag | Descripción | |------|-------------| | --skip-mdx | Omitir la validación de sintaxis MDX | | -v, --verbose | Mostrar salida de validación detallada | Ejecuta esto antes de desplegar para detectar errores a tiempo.

Analiza tu documentación en busca de enlaces internos rotos. Ejemplo de salida: Detecta enlaces a páginas faltantes y errores tipográficos. Consulta Enlaces y navegación para más detalles.

Corrige automáticamente las advertencias de enlaces internos rotos que tienen un destino inequívoco. Gestiona dos categorías: Anclas con errores tipográficos: un fragmento como #instalation que claramente debería ser #installation Desviación de anclas entre locales: una página traducida renombró sus encabezados, pero los enlaces en ese locale aún apuntan al fragmento en inglés original Ejemplo de salida en modo dry-run: Una corrección solo se escribe cuando el ancla corregida se resuelve a un encabezado real en la página de destino. Los casos ambiguos se dejan para revisión manual. Opciones: | Flag | Descripción | |------|-------------| | --dry-run | Vista previa de las correcciones planificadas sin escribir ningún archivo | | -y, --yes | Aplicar correcciones sin solicitud de confirmación | | --types | Lista de tipos de advertencia a corregir, separados por comas (por defecto: todos los admitidos) |

Renombra una página y actualiza automáticamente todas las referencias. Esto hará: Renombrar el archivo Actualizar la navegación de docs.json Actualizar enlaces en el resto de archivos MDX Actualizar referencias de snippets Usa esto en lugar de renombrar manualmente para mantener todas las referencias sincronizadas.

Sube tus docs y activa un build directamente desde la terminal. El progreso se muestra en vivo a medida que se completa cada fase del build. También disponible como jamdesk push. | Flag | Descripción | |------|-------------| | --detach | Encolar y salir inmediatamente | | --full-rebuild | Forzar reconstrucción completa (sin caché) | | --project | Desplegar en un proyecto específico | | --allow-empty | Permitir el despliegue con cero páginas de contenido .mdx (rechazado por defecto) |

Comprueba tu entorno y diagnostica problemas. Comprueba: Versión de Node.js (requiere v20+) Versión de npm Que docs.json existe y es válido Estado de la caché en ~/.jamdesk Permisos de escritura Ejecuta esto si tienes problemas con el CLI.

Vacía el directorio de caché ~/.jamdesk. Esto elimina dependencias en caché y artefactos de build. Úsalo para: Liberar espacio en disco Corregir problemas de caché dañada Forzar una instalación limpia de dependencias Las dependencias se reinstalarán en el siguiente jamdesk dev.

Actualiza el CLI a la última versión. También puedes actualizar manualmente:

Errores de sintaxis MDX

Los archivos MDX se parsean como JSX, así que ciertos caracteres tienen un significado especial. Problema habitual: el carácter < se interpreta como el inicio de una etiqueta JSX. Soluciones: Usa < para el menor que literal: Values <50% are low Reescribe para evitar el carácter: "Below 50%" en lugar de "<50%" Ejecuta jamdesk validate para ver mensajes de error detallados con números de línea

docs.json no encontrado

Asegúrate de estar en un directorio con un archivo docs.json. Soluciones: Ejecuta jamdesk init para crear un nuevo proyecto Comprueba que estás en el directorio correcto Verifica que el archivo se llama exactamente docs.json (no doc.json ni similar)

El servidor de desarrollo no arranca

El servidor de desarrollo puede fallar al iniciar por varios motivos. Prueba estos pasos: Ejecuta jamdesk doctor para comprobar tu entorno Ejecuta jamdesk clean para vaciar la caché Usa jamdesk dev --verbose para obtener salida de error detallada Comprueba que Node.js v20+ está instalado: node --version

Errores de permiso denegado

Es posible que no tengas permisos de escritura en el directorio de caché. Soluciones: Comprueba los permisos de ~/.jamdesk: ls -la ~/.jamdesk Corrige la propiedad: sudo chown -R $(whoami) ~/.jamdesk Ejecuta jamdesk clean y vuelve a intentarlo

Descripción general del CLI

Q: jamdesk broken-links

Analiza tu documentación en busca de enlaces internos rotos. Ejemplo de salida: Detecta enlaces a páginas faltantes y errores tipográficos. Consulta Enlaces y navegación para más detalles.

Q: jamdesk fix

Corrige automáticamente las advertencias de enlaces internos rotos que tienen un destino inequívoco. Gestiona dos categorías: Anclas con errores tipográficos: un fragmento como #instalation que claramente debería ser #installation Desviación de anclas entre locales: una página traducida renombró sus encabezados, pero los enlaces en ese locale aún apuntan al fragmento en inglés original Ejemplo de salida en modo dry-run: Una corrección solo se escribe cuando el ancla corregida se resuelve a un encabezado real en la página de destino. Los casos ambiguos se dejan para revisión manual. Opciones: | Flag | Descripción | |------|-------------| | --dry-run | Vista previa de las correcciones planificadas sin escribir ningún archivo | | -y, --yes | Aplicar correcciones sin solicitud de confirmación | | --types | Lista de tipos de advertencia a corregir, separados por comas (por defecto: todos los admitidos) |

Q: jamdesk openapi-check

Valida un único archivo de especificación OpenAPI. Valida: Sintaxis YAML/JSON válida Cumplimiento del esquema OpenAPI 3.x Definiciones de endpoints Las referencias $ref se resuelven correctamente

El CLI de Jamdesk te permite preview docs localmente, validar la configuración, detectar enlaces rotos y migrar desde otras plataformas. Es de código abierto bajo la Apache License 2.0.

Instalación

Instala globalmente desde npm para usar jamdesk desde cualquier lugar:

npm install -g jamdesk

Después de instalar, verifica que funciona:

jamdesk --version

Requisitos

Node.js v20.0.0 o superior
npm v8 o superior (recomendado)

Inicio rápido

Crear un proyecto

Crea un nuevo proyecto de documentación:

jamdesk init my-docs
cd my-docs

Iniciar el servidor de desarrollo

Ejecuta el servidor de desarrollo local con recarga en caliente:

jamdesk dev

Tus docs estarán disponibles en http://localhost:3000/docs

Validar antes de desplegar

Detecta errores de configuración, enlaces rotos y ortografía:

jamdesk validate
jamdesk broken-links
jamdesk fix --dry-run
jamdesk fix
jamdesk spellcheck

Comandos

Ejecuta jamdesk <command> --help para obtener información detallada sobre cualquier comando.

Desarrollo

Inicia el servidor de desarrollo local con recarga en caliente.

jamdesk dev
jamdesk dev --port 3001

Características:

Validación automática al iniciar (esquema de docs.json, sintaxis MDX y specs de OpenAPI referenciadas; una spec inválida detiene el servidor para que la detectes antes de desplegar)
Recarga en caliente al cambiar archivos MDX
Reconstrucción automática de la navegación al cambiar docs.json
CSS personalizado (style.css) recargado al actualizar el navegador
Funcionalidad de búsqueda completa
Todos los temas y componentes disponibles

Opciones:

Flag	Descripción
`-p, --port <port>`	Puerto en el que ejecutarlo (por defecto: 3000)
`-v, --verbose`	Habilitar salida detallada

Crea un nuevo proyecto de documentación.

jamdesk init              # Interactive mode
jamdesk init my-docs      # Create in new directory

Esto crea un nuevo proyecto con:

Archivo de configuración docs.json
Páginas MDX de ejemplo
Estructura de carpetas recomendada

Autenticación

Inicia sesión en Jamdesk desde tu navegador. Es necesario antes de desplegar.

jamdesk login

Abre el dashboard de Jamdesk en tu navegador para la autenticación. Las credenciales se almacenan localmente en ~/.jamdeskrc.

Guía de autenticación

Flujo de autenticación en el navegador, gestión de sesiones y solución de problemas

Elimina las credenciales almacenadas.

jamdesk logout

Muestra el usuario autenticado actual y verifica que tu sesión sea válida.

jamdesk whoami

Validación

Valida tu configuración de docs.json, la sintaxis MDX y las specs de OpenAPI.

jamdesk validate
jamdesk validate --skip-mdx

Comprueba:

Sintaxis JSON válida en docs.json
Campos obligatorios (name, navigation)
Valores de tema válidos
Errores de sintaxis MDX (por ejemplo, caracteres < sin escapar)
Validación de specs de OpenAPI (si está configurado)
Cumplimiento del esquema

Opciones:

Flag	Descripción
`--skip-mdx`	Omitir la validación de sintaxis MDX
`-v, --verbose`	Mostrar salida de validación detallada

Ejecuta esto antes de desplegar para detectar errores a tiempo.

Analiza tu documentación en busca de enlaces internos rotos.

jamdesk broken-links

Ejemplo de salida:

docs/getting-started.mdx:15 - /docs/quikstart
  Did you mean: /docs/quickstart

Found 1 broken link in 45 files.

Detecta enlaces a páginas faltantes y errores tipográficos. Consulta Enlaces y navegación para más detalles.

Corrige automáticamente las advertencias de enlaces internos rotos que tienen un destino inequívoco. Gestiona dos categorías:

Anclas con errores tipográficos: un fragmento como #instalation que claramente debería ser #installation
Desviación de anclas entre locales: una página traducida renombró sus encabezados, pero los enlaces en ese locale aún apuntan al fragmento en inglés original

# Preview what would change without touching any files
jamdesk fix --dry-run

# Apply fixes (prompts for confirmation)
jamdesk fix

Ejemplo de salida en modo dry-run:

Planned fixes:

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

(dry run — no files written)

Una corrección solo se escribe cuando el ancla corregida se resuelve a un encabezado real en la página de destino. Los casos ambiguos se dejan para revisión manual.

Opciones:

Flag	Descripción
`--dry-run`	Vista previa de las correcciones planificadas sin escribir ningún archivo
`-y, --yes`	Aplicar correcciones sin solicitud de confirmación
`--types <list>`	Lista de tipos de advertencia a corregir, separados por comas (por defecto: todos los admitidos)

Guía para corregir enlaces rotos

Recorrido paso a paso: vista previa, aplicación, revisión y commit

Comprueba tu documentación en busca de errores ortográficos.

jamdesk spellcheck

Ejemplo de salida:

getting-started.mdx:14 - "recieve"
  └─ Did you mean: receive

Found 3 misspellings across 24 pages.
Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words.

Usa un diccionario en inglés con más de 150 términos técnicos integrados (API, GraphQL, Kubernetes, React, etc.) para que la jerga habitual no se marque. Omite bloques de código, código en línea, frontmatter, JSX, URLs y rutas de archivo. Por ahora solo en inglés; se planea soporte de diccionario multilingüe.

Opciones:

Flag	Descripción
`--fix`	Corregir errores ortográficos de forma interactiva o añadirlos a la lista de ignorados
`--json`	Generar salida en JSON (para pipelines de CI)
`-v, --verbose`	Mostrar cada archivo a medida que se comprueba

Modo de corrección interactiva (--fix) recorre cada palabra mal escrita única:

1/10  "recieve" — found in 3 files
      intro.mdx:14, setup.mdx:7, guide.mdx:22

? What do you want to do?
❯ Fix → receive (recommended)
  Fix → relieve
  Ignore in the future (add to docs.json)
  Skip

Fix reemplaza la palabra con una sugerencia en todos los archivos (seguro para el texto en prosa, así que no modificará bloques de código ni atributos JSX). Se muestran hasta 3 sugerencias, con la mejor coincidencia marcada como recomendada.
Ignore añade la palabra a spellcheck.ignore en tu docs.json para que no se vuelva a marcar
Skip no hace nada en esta ejecución

Los cambios se muestran en vista previa y se confirman antes de aplicarse.

Lista de ignorados personalizada: añade términos específicos del proyecto a tu docs.json:

docs.json

{
  "spellcheck": {
    "ignore": ["YourProduct", "kubectl", "Terraform"]
  }
}

El nombre de tu proyecto de docs.json se ignora automáticamente.

Valida un único archivo de especificación OpenAPI.

jamdesk openapi-check openapi.yaml
jamdesk openapi-check api/spec.json

Valida:

Sintaxis YAML/JSON válida
Cumplimiento del esquema OpenAPI 3.x
Definiciones de endpoints
Las referencias $ref se resuelven correctamente

Tus specs de OpenAPI se validan en tres lugares. jamdesk dev se detiene al iniciar si una spec referenciada no es válida, y jamdesk validate / jamdesk openapi-check comprueban specs bajo demanda. Al desplegar, el build en la nube también valida tus specs referenciadas, pero ahí es una advertencia no fatal: el resto de tus docs se publica igualmente, y se te indica exactamente qué está mal (un error de parseo con línea y columna, un $ref sin resolver o un operationId duplicado) por email y en la lista de builds del dashboard. Corrige la spec y vuelve a hacer push para resolverlo.

Gestión de archivos

Renombra una página y actualiza automáticamente todas las referencias.

jamdesk rename docs/old-name.mdx docs/new-name.mdx

Esto hará:

Renombrar el archivo
Actualizar la navegación de docs.json
Actualizar enlaces en el resto de archivos MDX
Actualizar referencias de snippets

Usa esto en lugar de renombrar manualmente para mantener todas las referencias sincronizadas.

Migración

Migra documentación de Mintlify a Jamdesk.

jamdesk migrate

Detecta tu configuración de Mintlify y la convierte al formato de Jamdesk. En el mismo paso, renombra componentes obsoletos (por ejemplo, CardGroup → Columns), reubica archivos MDX de snippets huérfanos en /snippets/ y reescribe los imports relativos al padre, extrae componentes en línea que usan React hooks en /snippets/<name>.tsx con 'use client', y corrige automáticamente problemas mecánicos de sintaxis MDX. Es idempotente, así que puedes volver a ejecutarlo sin riesgo.

Guía de migración

Guía de migración completa con instrucciones paso a paso para Mintlify y otras plataformas

Despliegue

Sube tus docs y activa un build directamente desde la terminal.

jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuild

El progreso se muestra en vivo a medida que se completa cada fase del build. También disponible como jamdesk push.

Flag	Descripción
`--detach`	Encolar y salir inmediatamente
`--full-rebuild`	Forzar reconstrucción completa (sin caché)
`--project <id>`	Desplegar en un proyecto específico
`--allow-empty`	Permitir el despliegue con cero páginas de contenido `.mdx` (rechazado por defecto)

Guía de despliegue del CLI

Pipeline de despliegue completo, fases del build, referencia de errores y solución de problemas

Genera y despliega un Cloudflare Worker que hace de proxy de /docs en tu propio dominio hacia tu sitio de Jamdesk.

jamdesk deploy-proxy cloudflare
jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --skip-deploy --yes

Interactivo por defecto: comprueba Wrangler, verifica tu cuenta de Cloudflare, detecta automáticamente tu slug desde docs.json, genera los archivos del Worker y, opcionalmente, despliega.

Flag	Descripción
`--slug <slug>`	Slug del proyecto de Jamdesk
`--domain <domain>`	Dominio de destino (por ejemplo, `example.com`)
`--path <path>`	Prefijo de ruta (por defecto: `/docs`)
`--output-dir <dir>`	Directorio de salida (por defecto: `cloudflare-worker/`)
`--skip-deploy`	Generar solo los archivos, sin desplegar
`--force`	Sobrescribir el directorio existente sin preguntar
`--yes`	Omitir todas las solicitudes de confirmación (modo CI)

Guía de Cloudflare Workers

Configuración del Worker, patrones de rutas y configuración de caché

Mantenimiento

Comprueba tu entorno y diagnostica problemas.

jamdesk doctor

Comprueba:

Versión de Node.js (requiere v20+)
Versión de npm
Que docs.json existe y es válido
Estado de la caché en ~/.jamdesk
Permisos de escritura

Ejecuta esto si tienes problemas con el CLI.

Vacía el directorio de caché ~/.jamdesk.

jamdesk clean

Esto elimina dependencias en caché y artefactos de build. Úsalo para:

Liberar espacio en disco
Corregir problemas de caché dañada
Forzar una instalación limpia de dependencias

Las dependencias se reinstalarán en el siguiente jamdesk dev.

Actualiza el CLI a la última versión.

jamdesk update

También puedes actualizar manualmente:

npm update -g jamdesk

Configuración

Crea ~/.jamdeskrc para establecer opciones por defecto:

{
  "defaultPort": 3001,
  "verbose": false,
  "checkUpdates": true
}

Opción	Tipo	Por defecto	Descripción
`defaultPort`	number	3000	Puerto por defecto para el servidor de desarrollo
`verbose`	boolean	false	Habilitar salida detallada por defecto
`checkUpdates`	boolean	true	Comprobar actualizaciones del CLI al iniciar

Solución de problemas

Los archivos MDX se parsean como JSX, así que ciertos caracteres tienen un significado especial.

Problema habitual: el carácter < se interpreta como el inicio de una etiqueta JSX.

✗ Found 1 MDX syntax error(s)

  getting-started.mdx:42
    Unexpected character `5` (U+0035) before name
    Fix: A < character is being parsed as JSX. Use &lt; or rewrite

Soluciones:

Usa < para el menor que literal: Values <50% are low
Reescribe para evitar el carácter: "Below 50%" en lugar de "<50%"
Ejecuta jamdesk validate para ver mensajes de error detallados con números de línea

Asegúrate de estar en un directorio con un archivo docs.json.

Soluciones:

Ejecuta jamdesk init para crear un nuevo proyecto
Comprueba que estás en el directorio correcto
Verifica que el archivo se llama exactamente docs.json (no doc.json ni similar)

El servidor de desarrollo puede fallar al iniciar por varios motivos.

Prueba estos pasos:

Ejecuta jamdesk doctor para comprobar tu entorno
Ejecuta jamdesk clean para vaciar la caché
Usa jamdesk dev --verbose para obtener salida de error detallada
Comprueba que Node.js v20+ está instalado: node --version

La primera ejecución instala dependencias en ~/.jamdesk/node_modules.

Esto es normal y solo ocurre una vez. Las siguientes ejecuciones serán mucho más rápidas.

Otro proceso está usando el puerto por defecto.

Soluciones:

# Use a different port
jamdesk dev --port 3001

# Or set a default in ~/.jamdeskrc
{ "defaultPort": 3001 }

Es posible que no tengas permisos de escritura en el directorio de caché.

Soluciones:

Comprueba los permisos de ~/.jamdesk: ls -la ~/.jamdesk
Corrige la propiedad: sudo chown -R $(whoami) ~/.jamdesk
Ejecuta jamdesk clean y vuelve a intentarlo

¿Sigues teniendo problemas? Consulta la guía de solución de problemas del CLI o abre un issue en GitHub.

¿Qué sigue?

Autenticación

Flujo de inicio de sesión, sesiones y solución de problemas

Despliegue del CLI

Desplegar desde la terminal

Preview local

Opciones avanzadas de desarrollo local

Guía de migración

Migrar desde Mintlify u otras plataformas