Guía de Migración
¿Vienes de otra plataforma de documentación? Jamdesk puede automatizar la transición o migrar manualmente para tener control total.
Los proyectos de Mintlify tienen un camino de un solo comando: jamdesk migrate lee mint.json, escribe docs.json y reescribe tu MDX en su lugar. ¿Vienes de GitBook, Docusaurus, ReadMe, Confluence u otra plataforma? La pestaña "Otras Plataformas" describe los pasos manuales — son breves si puedes exportar tu contenido como Markdown.
Exporta como Markdown primero si puedes. Jamdesk está construido sobre MDX, por lo que cualquier contenido ya en Markdown se integra con un simple renombrado a .mdx y unas pocas líneas de frontmatter.
Elige Tu Ruta
El CLI realiza la mayor parte del trabajo por ti.
Migración Automatizada
npm install -g jamdeskjamdesk migrateDesde la raíz del proyecto, esto se ejecuta en un solo paso:
- Lee
mint.jsony escribedocs.json - Renombra componentes obsoletos en archivos MDX (p. ej.
CardGroup→Columns) - Mueve archivos MDX de snippets huérfanos a
/snippets/y reescribe cada importación relativa al directorio padre (../foo/bar.mdx) como una ruta relativa a la raíz (/snippets/foo/bar.mdx) - Extrae componentes inline que usan React hooks a
/snippets/<name>.tsxcon la directiva'use client', y reescribe el MDX original para importar desde/snippets/ - Corrige automáticamente problemas mecánicos de sintaxis MDX que provocarían errores en el build
El comando es idempotente — vuelve a ejecutarlo tras ediciones y solo procesa lo que es nuevo. Todo lo que no puede gestionar de forma segura se imprime como advertencia con el archivo, la importación y la acción a tomar.
Comprueba el docs.json generado y los archivos MDX. Verifica la estructura de navegación y cualquier advertencia impresa por el CLI.
Mapeo de Configuración
El CLI convierte mint.json a docs.json automáticamente. Estas son las diferencias clave para que puedas verificar el resultado.
Mintlify (mint.json):
{
"name": "My Docs",
"navigation": [
{ "group": "Getting Started", "pages": ["introduction", "quickstart"] }
],
"colors": { "primary": "#0D9373" },
"topbarLinks": [{ "name": "Blog", "url": "https://example.com/blog" }]
}Jamdesk (docs.json):
{
"$schema": "https://jamdesk.com/docs.json",
"name": "My Docs",
"theme": "jam",
"colors": { "primary": "#0D9373" },
"navbar": {
"links": [{ "label": "Blog", "href": "https://example.com/blog" }]
},
"navigation": {
"groups": [
{ "group": "Getting Started", "pages": ["introduction", "quickstart"] }
]
}
}Compatibilidad de Componentes
La mayoría de los componentes de Mintlify tienen equivalentes directos en Jamdesk. Algunos tienen nombres o sintaxis diferentes.
| Componente Mintlify | Equivalente en Jamdesk | Notas |
|---|---|---|
<Card> | <Card> | Misma sintaxis |
| CardGroup | <Columns> | Usa la prop cols para el número de columnas |
<Columns> | <Columns> | Misma sintaxis |
<Accordion> | <Accordion> | Misma sintaxis |
<Tabs> / <Tab> | <Tabs> / <Tab> | Misma sintaxis |
<Steps> / <Step> | <Steps> / <Step> | Misma sintaxis |
<CodeGroup> | <CodeGroup> | Misma sintaxis |
<Tip>, <Note>, <Warning> | <Tip>, <Note>, <Warning> | Misma sintaxis |
<ResponseField> | <ParamField> | Nombre diferente |
<Snippet> | Importar desde /snippets/ | Enfoque diferente |
Problemas Comunes
jamdesk migrate renombra CardGroup a Columns en todos los archivos MDX. La prop cols se mantiene sin cambios. Revisa los archivos que hayas editado después de ejecutar la migración.
Renombra <ResponseField> a <ParamField>. Las props son las mismas.
{/* Before */}
<ResponseField name="id" type="string" required>
The unique identifier
</ResponseField>
{/* After */}
<ParamField name="id" type="string" required>
The unique identifier
</ParamField>Jamdesk resuelve únicamente importaciones de /snippets/* relativas a la raíz. Los proyectos de Mintlify suelen mantener archivos MDX de snippets en cualquier parte del árbol e importarlos con rutas relativas al directorio padre (import X from '../shared/x.mdx').
jamdesk migrate realiza tres acciones en un solo paso:
- Detecta archivos MDX que se importan como snippets pero están fuera de
/snippets/, los mueve bajo/snippets/preservando su ruta relativa (para que los snippets con prefijo de idioma comode/foo.mdxno colisionen). - Reescribe cada importación de snippet relativa al directorio padre en todos los archivos MDX con la nueva ruta relativa a la raíz.
- Extrae cualquier componente inline que use React hooks a un archivo
'use client'en/snippets/<name>.tsxy reemplaza la exportación inline con una importación desde/snippets/.
Si usabas el elemento JSX <Snippet file="my-snippet.mdx" /> de Mintlify, sustitúyelo por una importación MDX — ese caso no se reescribe automáticamente:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />El reubicador es conservador — si tu proyecto no tiene navegación resuelta, o los movimientos planificados superan max(5, 25%) de todos los archivos MDX, se cancela sin modificar nada e indica el motivo. Vuelve a ejecutarlo tras resolver la causa de cancelación.
Tanto topbarLinks como topbarCtaButton de Mintlify se mapean a navbar.links en docs.json. El campo name pasa a ser label, y url pasa a ser href.