Typemark Documentation

Con tu agente de programación

Migra desde Docusaurus, MkDocs, Fern, Nextra, Notion, Confluence o un sitio en vivo entregándole el trabajo a Claude Code, Codex, Cursor o Gemini. El agente sigue esta guía y comprueba su trabajo con typemark check.

Actualizado el 19 nov 20264 min de lectura

Para las plataformas que Typemark no importa automáticamente, tu agente de programación hace la conversión. La CLI de Typemark lo inicia en tu carpeta con esta página como instrucciones, y el agente sigue trabajando hasta que typemark check pase.

El agente se ejecuta en tu equipo, con tu propio inicio de sesión en el proveedor de tu agente. Tu contenido no pasa por Typemark hasta que lo subes.

Ejecútalo

  1. Instala la CLI y tu agente

    npm install -g @gettypemark/cli

    También necesitas uno de estos agentes instalado y con sesión iniciada: Claude Code (claude), Codex (codex), la CLI de Cursor (cursor-agent) o Gemini CLI (gemini).

  2. Inicia la migración

    Crea una carpeta vacía para tu nuevo sitio y ejecuta la migración desde ella, apuntando --source a tu documentación antigua: una carpeta, un repositorio de Git o la dirección del sitio en vivo.

    mkdir my-docs && cd my-docs
    typemark migrate --agent claude --source ../old-docs

    Usa --agent codex, --agent cursor o --agent gemini para los demás. Añade --from gitbook, --from readme o --from mintlify cuando estés terminando una de esas importaciones.

  3. Revisa y publica

    Cuando el agente termine, enumera lo que no se trasladó. Previsualiza el sitio con typemark dev y luego publícalo:

    typemark login
    typemark create "My Docs"    # crea el proyecto y vincula esta carpeta
    typemark push --prune --wait

¿Usas otro agente? Ejecuta typemark migrate --guide para imprimir las instrucciones y pégalas en él.

La guía que sigue tu agente

El resto de esta página está escrita para el agente. También es una buena lista de verificación si migras a mano.

Objetivo

Convierte la documentación de origen en un sitio de Typemark en la carpeta actual: un typemark.json en la raíz y un archivo .mdx por página. Conserva cada página, mantén las URL de las páginas siempre que sea posible, y termina solo cuando typemark check no reporte errores.

Reglas

  • Nunca modifiques el origen. Lee desde --source; escribe solo en la carpeta actual.
  • Usa primero typemark migrate cuando el origen sea Mintlify, GitBook o ReadMe. Convierte la mayor parte del sitio; tú terminas el resto.
  • Conserva las URL. Una página en /guides/auth del sitio antiguo va a guides/auth.mdx. Cuando una ruta tenga que cambiar, añade una redirección en typemark.json.
  • Solo contenido. Typemark nunca ejecuta código de una página. Elimina las instrucciones import y export, y convierte los componentes de React personalizados y las expresiones de JavaScript en Markdown o en los componentes de abajo. Los props literales como cols={3} están bien.
  • No inventes contenido. Copia el texto tal cual. Si algo no se puede convertir, deja una nota breve en tu informe final en lugar de adivinar.
  • Guarda primero un sitio en vivo. Cuando el origen es una URL, descarga cada página que necesites en una carpeta temporal antes de convertir, y trabaja a partir de esos archivos.

Pasos

  1. Inventario. Enumera cada página del origen y su URL. Localiza la navegación: sidebars.js (Docusaurus), nav de mkdocs.yml (MkDocs), docs.yml (Fern), los archivos _meta.json (Nextra), la barra lateral en .vitepress/config (VitePress) o la estructura de carpetas de una exportación.

  2. Escribe typemark.json. Las pestañas contienen grupos, los grupos contienen páginas, y una página es su ruta sin la extensión:

    {
      "$schema": "https://typemark.dev/schema.json",
      "name": "Acme Docs",
      "colors": { "primary": "#4f46e5" },
      "navigation": {
        "tabs": [
          {
            "tab": "Documentation",
            "groups": [
              { "group": "Getting started", "pages": ["introduction", "quickstart"] },
              { "group": "Guides", "pages": ["guides/auth", "guides/webhooks"] }
            ]
          },
          {
            "tab": "API Reference",
            "groups": [{ "group": "Endpoints", "pages": [{ "source": "openapi.yaml" }] }]
          }
        ]
      },
      "redirects": [{ "from": "/old-path", "to": "/new-path" }]
    }

    Los grupos no se anidan: pon las páginas de una sección anidada en su propio grupo, justo después de su padre. Consulta typemark.json y Navigation.

  3. Convierte cada página a .mdx con frontmatter. title es obligatorio; el sitio lo muestra como encabezado de la página, así que elimina un primer # Heading que lo repita. Añade description cuando el origen la tenga.

    ---
    title: Authentication
    description: Authenticate requests with an API key.
    ---
  4. Asigna componentes con la tabla de abajo.

  5. Mueve las imágenes a images/ (o conserva su carpeta) y actualiza los enlaces. Descarga las imágenes alojadas en los servidores de la plataforma antigua.

  6. Traslada las traducciones, si el origen las tiene (como las carpetas i18n/<locale>/ de Docusaurus): enumera los idiomas en languages de typemark.json, con el idioma predeterminado primero, y coloca cada página traducida en <code>/<page>.mdx, la misma ruta que la página que traduce, dentro de una carpeta con el nombre de su código de idioma. No añadas traducciones a la navegación. Consulta Languages.

  7. Comprueba con typemark check y corrige cada error. Repite hasta que pase. Previsualiza con typemark dev si puedes.

  8. Informa de lo que no se trasladó: páginas omitidas, componentes que simplificaste, redirecciones añadidas.

Componentes

En el origenEn Typemark
Admoniciones: :::note, :::tip, :::warning, :::danger (Docusaurus, VitePress), !!! note (MkDocs), > [!NOTE] (GitHub)<Callout type="info">, type="tip", type="warning" o type="danger". Añade title="…" para un título personalizado
Pestañas<Tabs> con hijos <Tab title="…">
Bloques de código con pestañas<CodeGroup> con un bloque delimitado por pestaña, cada uno con un título: ```bash npm
Un bloque de código con nombre de archivo```js title="index.js"
Secciones desplegables, <details><Accordion title="…">; varias seguidas van en <AccordionGroup>
Tutoriales numerados<Steps> con hijos <Step title="…">
Tarjetas de enlace y mosaicos<Card title="…" icon="…" href="/path"> dentro de <CardGroup cols={2}>
Imágenes con pies de foto<Frame caption="…"><img src="/images/x.png" alt="…" /></Frame>
Parámetros de la API<ParamField query="name" type="string" required>, o path, header o body en lugar de query
Campos de respuesta<ResponseField name="…" type="…">
Entradas de changelog<Update label="March 2026">
Insignias<Badge>Beta</Badge>
Especificaciones OpenAPICopia la especificación a la carpeta y añade { "source": "openapi.yaml" } a la navegación
Cualquier otra cosaMarkdown simple que conserve el significado

Los iconos son nombres de Heroicons, como rocket-launch. La sintaxis completa de cada componente está en MDX Components en la barra lateral, por ejemplo Callouts y Cards.

Listo cuando

  • typemark check no reporta errores.
  • Cada página del inventario está en la navegación, redirigida o listada en tu informe.
  • La carpeta de origen no ha cambiado.