---
title: Guía de Migración
description: ¿Vienes de otra plataforma de documentación? Jamdesk puede automatizar la transición o migrar manualmente para tener control total.
---


  See the clean markdown version of this page at https://jamdesk.com/docs/setup/migration.md





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.

<YouTube id="DvIHWeBliK0" />

<Info>
**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.
</Info>

## Elige Tu Ruta

<Tabs>
  <Tab title="Desde Mintlify">
    El CLI realiza la mayor parte del trabajo por ti.

    <Card title="Guía de Migración de Mintlify a Jamdesk" icon="book-open" href="https://jamdesk.com/blog/migrating-from-mintlify-to-jamdesk">
      Lee el tutorial de migración con contexto, ejemplos y consejos.
    </Card>

    ### Migración Automatizada

    <Steps>
      <Step title="Instala el CLI">
        ```bash
        npm install -g jamdesk
        ```
      </Step>
      <Step title="Ejecuta la migración">
        ```bash
        jamdesk migrate
        ```

        Desde la raíz del proyecto, esto se ejecuta en un solo paso:

        - Lee `mint.json` y escribe `docs.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>.tsx` con 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.
      </Step>
      <Step title="Revisa y ajusta">
        Comprueba el `docs.json` generado y los archivos MDX. Verifica la estructura de navegación y cualquier advertencia impresa por el CLI.
      </Step>
    </Steps>

    ### 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`):**
    ```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`):**
    ```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

    <AccordionGroup>
      <Accordion title="CardGroup pasa a llamarse Columns">
        `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.
      </Accordion>
      <Accordion title="ResponseField pasa a llamarse ParamField">
        Renombra `<ResponseField>` a `<ParamField>`. Las props son las mismas.

        ```mdx
        {/* Before */}
        <ResponseField name="id" type="string" required>
          The unique identifier
        </ResponseField>

        {/* After */}
        <ParamField name="id" type="string" required>
          The unique identifier
        </ParamField>
        ```
      </Accordion>
      <Accordion title="Los snippets se reubican y reconectan automáticamente">
        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 como `de/foo.mdx` no 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>.tsx` y 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:

        ```mdx
        {/* 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.
      </Accordion>
      <Accordion title="topbarLinks se mapea a navbar.links">
        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`.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Desde Otras Plataformas">
    Para GitBook, ReadMe, Docusaurus, Confluence, Notion u otras herramientas de documentación.

    <Tip>
      ¿Necesitas ayuda con tu migración? [Escríbenos](mailto:contact@jamdesk.com) y te ayudaremos a configurarlo.
    </Tip>

    ### Desde GitBook

    GitBook almacena el contenido como Markdown con un archivo `SUMMARY.md` para la navegación.

    <Steps>
      <Step title="Exporta tu contenido">
        Exporta tu espacio de GitBook como Markdown. Si usas la sincronización Git de GitBook, tu contenido ya está en un repositorio Git como archivos `.md`.
      </Step>
      <Step title="Convierte los archivos a MDX">
        Renombra los archivos `.md` a `.mdx` y añade frontmatter a cada archivo:

        ```mdx
        ---
        title: Your Page Title
        description: A short description of the page
        ---

        Your existing Markdown content here.
        ```
      </Step>
      <Step title="Mapea la navegación desde SUMMARY.md">
        GitBook usa `SUMMARY.md` para definir su barra lateral. Conviértelo a grupos de navegación en `docs.json`.

        **GitBook (`SUMMARY.md`):**
        ```markdown
        # Summary

        ## Getting Started
        * [Introduction](introduction.md)
        * [Quick Start](quickstart.md)

        ## API Reference
        * [Authentication](api/auth.md)
        ```

        **Jamdesk (`docs.json`):**
        ```json
        {
          "navigation": {
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              },
              {
                "group": "API Reference",
                "pages": ["api/auth"]
              }
            ]
          }
        }
        ```
      </Step>
      <Step title="Mueve las imágenes">
        Mueve todas las imágenes a un directorio `/images` y actualiza las referencias en tus archivos MDX para usar rutas absolutas (p. ej., `/images/screenshot.png`).
      </Step>
      <Step title="Prueba en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### Desde Docusaurus

    Los proyectos de Docusaurus ya usan MDX, por lo que la mayoría del contenido se transfiere directamente.

    <Steps>
      <Step title="Copia tus archivos MDX">
        Copia el contenido del directorio `docs/` de tu proyecto Docusaurus a la raíz de tu proyecto Jamdesk. Mantén la estructura de directorios existente.
      </Step>
      <Step title="Limpia el frontmatter">
        Elimina los campos de frontmatter específicos de Docusaurus. Conserva `title` y `description`, elimina el resto.

        ```yaml
        ---
        # Remove these Docusaurus fields
        sidebar_position: 3
        sidebar_label: "Custom Label"
        slug: /custom-url
        pagination_next: null

        # Keep these
        title: Your Page Title
        description: A short description
        ---
        ```
      </Step>
      <Step title="Mapea sidebars.js a docs.json">
        Convierte la estructura de categorías de tu `sidebars.js` a grupos de navegación en `docs.json`.

        **Docusaurus (`sidebars.js`):**
        ```javascript
        module.exports = {
          docs: [
            {
              type: 'category',
              label: 'Getting Started',
              items: ['intro', 'installation'],
            },
          ],
        };
        ```

        **Jamdesk (`docs.json`):**
        ```json
        {
          "navigation": {
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["intro", "installation"]
              }
            ]
          }
        }
        ```
      </Step>
      <Step title="Reemplaza los componentes de Docusaurus">
        Sustituye los componentes específicos de Docusaurus por sus equivalentes en Jamdesk.

        | Docusaurus | Jamdesk | Ejemplo |
        |---|---|---|
        | `:::note` / `:::tip` / `:::warning` | `<Note>` / `<Tip>` / `<Warning>` | Ver [componentes de llamada](/es/components/overview) |
        | `import Tabs from '@theme/Tabs'` | `<Tabs>` (disponible globalmente) | No se necesita importación |
        | `import TabItem from '@theme/TabItem'` | `<Tab>` (disponible globalmente) | Usa `title` en lugar de `label` |
      </Step>
      <Step title="Prueba en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>

    ### Desde Otras Herramientas

    Para Confluence, Notion, ReadMe u otra plataforma, el proceso es el mismo: exporta tu contenido a Markdown y luego configura la estructura del proyecto Jamdesk.

    <Steps>
      <Step title="Exporta como Markdown">
        La mayoría de las plataformas tienen una opción de exportación a Markdown o HTML. Usa Markdown si está disponible. Para HTML, conviértelo a Markdown con una herramienta como [Pandoc](https://pandoc.org/).

        ```bash
        # Convert HTML to Markdown with Pandoc
        pandoc input.html -f html -t markdown -o output.md
        ```
      </Step>
      <Step title="Crea docs.json">
        Comienza con una configuración mínima y construye tu navegación a medida que añades páginas.
      </Step>
      <Step title="Convierte los archivos a MDX">
        Renombra los archivos `.md` a `.mdx` y añade frontmatter (`title`, `description`) a cada archivo.
      </Step>
      <Step title="Mueve los recursos">
        Mueve imágenes y otros recursos a un directorio `/images`. Actualiza las referencias de archivos para usar rutas absolutas.
      </Step>
      <Step title="Prueba en local">
        ```bash
        jamdesk dev
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Lista de Verificación Post-Migración

<Check>Todas las páginas se renderizan sin errores</Check>
<Check>La estructura de navegación coincide con el sitio original</Check>
<Check>Los enlaces internos funcionan correctamente</Check>
<Check>Las imágenes y los recursos se muestran correctamente</Check>
<Check>Los bloques de código tienen el resaltado de sintaxis correcto</Check>
<Check>La búsqueda indexa tu contenido</Check>

## ¿Qué Sigue?

<Columns cols={2}>
  <Card title="Estructura de Directorios" icon="folder-tree" href="/es/setup/directory-structure">
    Aprende a organizar tu documentación
  </Card>
  <Card title="Referencia de docs.json" icon="gear" href="/es/config/docs-json-reference">
    Configura los ajustes de tu sitio
  </Card>
</Columns>