Typemark Documentation

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

  1. 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.

  2. 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.

  3. Elige el repositorio

    Typemark muestra ReadMe project detected. Haz clic en Import y confirma.

  4. 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.

  5. 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 en images/ y actualiza los enlaces antes de cancelar ReadMe. Tu agente de programación puede hacerlo por ti.

  6. 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

ReadMeTypemark
Carpetas de categoría en docs/Grupos de navegación con el nombre de la carpeta, en una pestaña Guides
Archivos de páginaSe 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.yamlOrden de las páginas dentro del grupo. Los archivos se eliminan
Una carpeta con index.md y subpáginasLa 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 referenciaPáginas de API generadas en la pestaña API Reference
titletitle
excerptLa descripción de la página, tal cual
hidden: trueOculta 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 glosarioTexto plano
Comentarios HTMLSe eliminan, ya que no se compilan en MDX
Recetas y páginas personalizadasPáginas normales, en los grupos Recipes y Pages

No se traslada

  • Imágenes en files.readme.io siguen 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.