Guía de migración
¿Vienes de otra plataforma de documentación? Jamdesk puede automatizar la transición, o puedes migrar manualmente para tener control total.
Los proyectos de Mintlify tienen una ruta de un solo comando: jamdesk migrate lee mint.json, escribe docs.json y reescribe tu MDX en el mismo lugar. ¿Vienes de GitBook, Docusaurus, ReadMe, Confluence o algún otro lugar? La pestaña "Otras plataformas" recorre los pasos manuales. Son breves si puedes extraer tu contenido como Markdown.
Exporta como Markdown primero si puedes. Jamdesk está construido sobre MDX, así que cualquier cosa que ya esté en Markdown se integra con solo renombrar a .mdx y añadir unas líneas de frontmatter.
Elige tu ruta
La 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 (por ejemplo,
CardGroup→Columns) - Mueve archivos MDX de snippet huérfanos a
/snippets/y reescribe cada importación relativa al padre (../foo/bar.mdx) a una relativa a la raíz (/snippets/foo/bar.mdx) - Extrae componentes en línea que usan React hooks a
/snippets/<name>.tsxcon la directiva'use client', y luego reescribe el MDX original para importar desde/snippets/ - Corrige automáticamente problemas mecánicos de sintaxis MDX que harían fallar el build
El comando es idempotente: vuelve a ejecutarlo después de hacer cambios y solo detectará lo nuevo. Cualquier cosa que no pueda manejar de forma segura se imprime como advertencia con el archivo, la importación y la acción a tomar.
Revisa el docs.json generado y los archivos MDX. Verifica la estructura de navegación y cualquier advertencia impresa por la CLI.
Mapeo de configuración
La 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. Unos pocos tienen nombres o sintaxis diferentes.
| Componente de 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> | Importación desde /snippets/ | Enfoque diferente |
Problemas comunes
jamdesk migrate renombra CardGroup a Columns por ti en todos los archivos MDX. La prop cols se mantiene sin cambios. Revisa cualquier archivo 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 solo resuelve importaciones /snippets/* relativas a la raíz. Los proyectos de Mintlify a menudo mantienen archivos MDX de snippet en cualquier parte del árbol y los importan 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 los snippets con prefijo de idioma comode/foo.mdxno colisionen). - Reescribe cada importación de snippet relativa al padre en cada archivo MDX a la nueva ruta relativa a la raíz.
- Extrae cualquier componente en línea que use React hooks a un archivo
'use client'en/snippets/<name>.tsxy reemplaza la exportación en línea con una importación desde/snippets/.
Si usaste el elemento JSX <Snippet file="my-snippet.mdx" /> de Mintlify, cámbialo por una importación 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 exceden max(5, 25%) de todos los archivos MDX, aborta sin tocar nada y te dice por qué. Vuelve a ejecutarlo después de corregir el motivo del aborto.
topbarLinks y topbarCtaButton de Mintlify se mapean ambos a navbar.links en docs.json. El campo name se convierte en label, y url se convierte en href.