Desde ReadMe
Sincroniza tu proyecto de ReadMe con GitHub, o expórtalo, e importa el repositorio. Las carpetas de categoría se convierten en tu navegación, el orden de las páginas viene de _order.yaml, y tu MDX conserva su sintaxis.
Actualizado el 19 nov 20264 min de lectura
ReadMe puede escribir un proyecto en un repositorio de GitHub mediante su sincronización bidireccional, como archivos Markdown en carpetas. Typemark importa ese repositorio: cada carpeta de categoría se convierte en un grupo de navegación, _order.yaml define el orden de las páginas y tus páginas de referencia de API muestran sus endpoints a partir de tus archivos OpenAPI.
Las páginas de ReadMe son MDX, así que Typemark las lee tal cual: excerpt funciona como la descripción de la página y <Callout>, <Image>, <Cards> y <Embed> se renderizan sin cambios. La importación mueve los archivos para que tus URL no cambien, y convierte lo que solo se muestra en ReadMe, como los callouts con emojis y los enlaces doc:, en un único commit que puedes revisar.
Antes de empezar
- Tu plan de ReadMe incluye la sincronización con GitHub, o puedes exportar el proyecto. Revisa tu plan en ReadMe.
- La sincronización de ReadMe necesita un repositorio nuevo y vacío: sin commits y sin README.
- El repositorio pesa 100 MB o menos.
Importa tu proyecto
Sincroniza el proyecto con GitHub
En ReadMe, conecta el proyecto a un repositorio de GitHub nuevo y vacío. ReadMe escribirá
docs/,reference/y las demás carpetas en él. Cada versión de ReadMe es una rama; Typemark importa la que elijas al conectar, la rama por defecto a menos que selecciones otra.Crea un proyecto en Typemark
Haz clic en New project, ponle un nombre y, en Start from, elige Import from GitHub. Haz clic en Create and connect GitHub y concede a la GitHub App de Typemark acceso al repositorio.
Elige el repositorio
Typemark muestra ReadMe project detected. Haz clic en Import y confirma.
Revisa la importación
Typemark escribe
typemark.json, convierte la sintaxis heredada en un commit, lo sube y construye tu sitio. La vista general del proyecto muestra el resumen de la importación.Traslada tus imágenes
Las imágenes que subiste a ReadMe están alojadas en
files.readme.io. Siguen funcionando por ahora, pero residen en ReadMe. El resumen enumera cada página que las usa: descárgalas enimages/y actualiza los enlaces antes de cancelar ReadMe. Tu agente de programación puede hacerlo por ti.Desactiva la sincronización y publica
Desconecta la sincronización con GitHub en ReadMe, completa la lista de verificación para publicar y haz clic en Go live en Settings > Publishing.
Qué se convierte
| ReadMe | Typemark |
|---|---|
Carpetas de categoría en docs/ | Grupos de navegación con el nombre de la carpeta, en una pestaña Guides |
| Archivos de página | Se mueven para coincidir con las URL de ReadMe, así que /docs/my-page sigue siendo /docs/my-page. Las redirecciones cubren las URL planas antiguas de las páginas anidadas |
_order.yaml | Orden de las páginas dentro del grupo. Los archivos se eliminan |
Una carpeta con index.md y subpáginas | La página índice, seguida de sus subpáginas, en el mismo grupo |
Páginas de referencia de API (api: con un operationId) | Páginas de endpoint en la misma URL y en el mismo lugar, en una pestaña API Reference. Cada una muestra el endpoint de tu especificación junto con el texto propio de la página. Typemark añade openapi: "<spec> METHOD /path" al frontmatter |
Archivos OpenAPI en reference/ sin páginas de referencia | Páginas de API generadas en la pestaña API Reference |
title | title |
excerpt | La descripción de la página, tal cual |
hidden: true | Oculta en la barra lateral, aunque sigue accesible por URL |
<Callout icon="📘" theme="info"> | Se renderiza como callout y se abre en el editor visual. Se guarda tal como está escrito |
<Image>, <Cards>, <Columns>, <Embed>, <Table>, <Anchor> | Se renderizan tal como están escritos. Un <Embed> de un vídeo de YouTube, Vimeo, Loom o Wistia lo reproduce |
Callouts con emoji > 📘 Title | <Callout> con el tema correspondiente |
Enlaces doc:, ref: y recipe: | Enlaces a la página de Typemark |
| Términos del glosario | Texto plano |
| Comentarios HTML | Se eliminan, ya que no se compilan en MDX |
| Recetas y páginas personalizadas | Páginas normales, en los grupos Recipes y Pages |
No se traslada
- Imágenes en
files.readme.iosiguen siendo remotas hasta que las muevas. Consulta el paso 5. - Más de una versión. Un proyecto importa una rama, la que elijas al conectar.
- Ajustes de "Try it" de la API y claves guardadas. Las páginas de API de Typemark muestran la referencia de tu especificación.
- Variables como
<<company>>se mantienen como texto y aparecen en el resumen. - Entradas del changelog en
changelogs/no se importan. Vuelve a crear las que necesites con entradas de changelog. <HTMLBlock>y<TutorialTile>no son compatibles y aparecen en el resumen.- CSS personalizado y otros ajustes que viven en ReadMe en lugar de en el repositorio.
Desde tu terminal
Para convertir una exportación o un repositorio sincronizado en tu ordenador:
cd my-readme-project
typemark migrate # detects the ReadMe project and converts it, then offers to create the project and push it
Responde sí dos veces y tu sitio estará en Typemark, sin conexión hasta que lo publiques. En CI o con un agente de programación, usa typemark migrate --create "My Docs" --push en su lugar.
typemark migrate escribe los mismos cambios que la importación desde GitHub. Haz commit o guarda tu trabajo antes, para poder revisar el resultado con git diff.
Con tu agente de programación
Tu agente de programación puede descargar las imágenes de files.readme.io, fusionar las recetas en guías y corregir lo que enumere el resumen:
typemark migrate --from readme --agent claude
Consulta Con tu agente de programación.