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
Instala la CLI y tu agente
npm install -g @gettypemark/cliTambié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).Inicia la migración
Crea una carpeta vacía para tu nuevo sitio y ejecuta la migración desde ella, apuntando
--sourcea 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-docsUsa
--agent codex,--agent cursoro--agent geminipara los demás. Añade--from gitbook,--from readmeo--from mintlifycuando estés terminando una de esas importaciones.Revisa y publica
Cuando el agente termine, enumera lo que no se trasladó. Previsualiza el sitio con
typemark devy 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 migratecuando 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/authdel sitio antiguo va aguides/auth.mdx. Cuando una ruta tenga que cambiar, añade una redirección entypemark.json. - Solo contenido. Typemark nunca ejecuta código de una página. Elimina las instrucciones
importyexport, y convierte los componentes de React personalizados y las expresiones de JavaScript en Markdown o en los componentes de abajo. Los props literales comocols={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
-
Inventario. Enumera cada página del origen y su URL. Localiza la navegación:
sidebars.js(Docusaurus),navdemkdocs.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. -
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.
-
Convierte cada página a
.mdxcon frontmatter.titlees obligatorio; el sitio lo muestra como encabezado de la página, así que elimina un primer# Headingque lo repita. Añadedescriptioncuando el origen la tenga.--- title: Authentication description: Authenticate requests with an API key. --- -
Asigna componentes con la tabla de abajo.
-
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. -
Traslada las traducciones, si el origen las tiene (como las carpetas
i18n/<locale>/de Docusaurus): enumera los idiomas enlanguagesdetypemark.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. -
Comprueba con
typemark checky corrige cada error. Repite hasta que pase. Previsualiza contypemark devsi puedes. -
Informa de lo que no se trasladó: páginas omitidas, componentes que simplificaste, redirecciones añadidas.
Componentes
| En el origen | En 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 OpenAPI | Copia la especificación a la carpeta y añade { "source": "openapi.yaml" } a la navegación |
| Cualquier otra cosa | Markdown 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 checkno 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.