Guía de Migración
¿Migrando desde otra plataforma de documentación? Jamdesk puede ayudar a automatizar la transición, o puedes migrar manualmente para mayor control.
Los proyectos de Mintlify tienen una ruta 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 otro lugar? La pestaña "Otras Plataformas" explica 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 entra directamente con un renombre a .mdx y unas pocas líneas de frontmatter.
Elige Tu Ruta
El CLI hace 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 import relativo al padre (../foo/bar.mdx) a uno relativo a la raíz (/snippets/foo/bar.mdx) - Extrae componentes inline que usan React hooks a
/snippets/<name>.tsxcon la directiva'use client', luego reescribe el MDX original para importar desde/snippets/ - Corrige automáticamente problemas sintácticos mecánicos de MDX que harían fallar el build
El comando es idempotente — vuelve a ejecutarlo después de editar y solo recoge lo que es nuevo. Cualquier cosa que no pueda manejar de forma segura se imprime como advertencia con el archivo, el import 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 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> | Import 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 se mantienen igual.
{/* 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 imports /snippets/* relativos a la raíz. Los proyectos de Mintlify suelen mantener archivos MDX de snippets en cualquier lugar del árbol e importarlos con rutas relativas al padre (import X from '../shared/x.mdx').
jamdesk migrate hace tres cosas aquí en un solo paso:
- Detecta archivos MDX que se importan como snippets pero viven fuera de
/snippets/, y los mueve bajo/snippets/preservando su ruta relativa (para que snippets con prefijo de idioma comode/foo.mdxno colisionen). - Reescribe cada import de snippet relativo al padre en cada archivo MDX a 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 el export inline con un import desde/snippets/.
Si usabas el elemento JSX <Snippet file="my-snippet.mdx" /> de Mintlify, sustitúyelo por un import MDX — ese no se reescribe automáticamente:
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />
{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'
<MySnippet />El relocalizador es conservador — si tu proyecto no tiene navegación resuelta, o los movimientos planeados superan max(5, 25%) de todos los archivos MDX, se cancela sin tocar nada e indica el motivo. Vuelve a ejecutar después de corregir la causa de la cancelación.
topbarLinks y topbarCtaButton de Mintlify se mapean ambos a navbar.links en docs.json. El campo name pasa a ser label, y url pasa a ser href.