Convirtiendo Ami Pro .SAM a Markdown para Docs Pipelines

TL;DR

Elige Markdown cuando el contenido se dirija a un repositorio, un generador de sitios estáticos o una canalización de texto. Markdown es pequeño, fácil de diferenciar y portátil: los encabezados, listas, tablas y enlaces se conservan, los diagramas extraídos se convierten en archivos de imagen vinculados, y las ecuaciones pueden conservar su LaTeX. Combinado con Git, un archivo Ami Pro convertido puede revisarse en solicitudes de extracción en lugar de confiar en la fe. Convierte con Ami Pro Converter.

Por qué Markdown para documentos antiguos

Docs-as-code cambió lo que significa “tener documentación”. El contenido en un repositorio obtiene historial de versiones, revisión de código, verificación automática de enlaces y una canalización de compilación. El contenido en un formato binario propietario no obtiene nada de eso, y un archivo .sam obtiene menos que nada, porque ninguna herramienta en la cadena puede siquiera leerlo.

Convertir a Markdown mueve décadas de material al mismo flujo de trabajo que todo lo demás. Un procedimiento de instalación de 1995 se convierte en un archivo con el que puedes hacer diferencias respecto a su revisión de 2002, anotarlo en una solicitud de extracción y publicarlo a través del mismo generador de sitios estáticos que las notas de la versión de este trimestre.

Markdown también es la opción práctica más duradera disponible. Es texto plano con una capa de convención ligera: legible sin ningún software, analizables por docenas de implementaciones y convertible a HTML, PDF, DOCX o cualquier otra cosa a demanda. Dado que todo el problema comenzó con un formato de proveedor que sobrevivió a su proveedor, esa portabilidad es el objetivo.

Qué se mapea limpiamente y qué no

Markdown es deliberadamente minimalista, lo cual es su fortaleza y su límite. La estructura se traduce bien; la presentación no, y eso generalmente está bien porque la presentación es la capa que de todos modos quieres reemplazar.

Encabezados — los estilos Ami Pro de la hoja .STY se convierten en niveles de encabezado Markdown, proporcionando una estructura real al documento
Listas — las listas con viñetas y numeradas se convierten en listas estándar Markdown, incluyendo anidación
Énfasis: negrita y cursiva se traducen directamente; subrayado no tiene un equivalente Markdown y normalmente se convierte en énfasis
Tablas: las tablas simples se convierten en tablas de tuberías; los diseños complejos con celdas combinadas no se pueden representar y necesitan HTML como alternativa o una nota
Imágenes: los diagramas WMF/EMF extraídos se escriben como archivos y se referencian con la sintaxis de imagen estándar
Ecuaciones: disponibles en LaTeX para renderizadores con capacidad matemática, o como imágenes enlazadas donde no lo estén

Las hojas de estilo son lo que hace posibles los encabezados

Este es el detalle que decide si la conversión de Markdown es útil o inútil. Markdown no tiene concepto de "Helvetica negrita de 16 puntos" — tiene niveles de encabezado. La única manera en que un convertidor puede saber que una línea es un encabezado de nivel dos en lugar de un párrafo enfatizado es resolviendo el estilo de párrafo contra la hoja de estilos .STY.

Con la hoja de estilo presente, un documento convertido llega con una jerarquía de encabezados de la que puedes construir una tabla de contenido y dividir en secciones. Sin ella, obtienes una secuencia plana de párrafos con líneas en negrita ocasionales, y todos los beneficios mencionados anteriormente se evaporan.

Así que antes de convertir un archivo para una tubería de documentos, verifica que los archivos .STY se hayan transferido desde el servidor antiguo. Toma un minuto y determina el resultado de todo el proyecto.

Manejo de imágenes en un repositorio

1. Decide dónde viven los activos

La mayoría de los generadores de sitios estáticos esperan que las imágenes estén en un directorio dedicado o colocadas junto con la página. Elige la convención antes de convertir para que estés moviendo los archivos una sola vez, y no renombrando referencias en miles de Markdown archivos después.

2. Observar el tamaño del repositorio

Los diagramas extraídos se suman. Unos pocos miles de documentos con figuras pueden añadir cientos de megabytes a un repositorio que antes era solo de texto. Considera Git LFS, o mantén los recursos en almacenamiento de objetos y haz referencia a ellos mediante URL.

3. Normalizar nombres de archivos

Los archivos heredados están llenos de nombres de la era DOS, espacios y mayúsculas y minúsculas mezcladas. Normaliza a nombres en minúsculas con guiones durante la migración y mantén una tabla de correspondencia para que aún puedas rastrear una página publicada hasta tu archivo original .sam.

4. Elige una estrategia de ecuación desde el principio

Si su sitio muestra matemáticas, usa el LaTeX extraído y obtén fórmulas nítidas, seleccionables y buscables. Si no lo hace, usa imágenes renderizadas y acepta que las matemáticas no sean buscables. Mezclar ambos en un solo archivo es la opción que se debe evitar.

Revisando miles de archivos convertidos

Nadie lee tres mil archivos Markdown, pero Git hace que la revisión selectiva sea manejable de una manera que una carpeta de archivos DOCX no lo hace. Realiza la conversión como un único gran commit en una rama, luego revisa por patrón en lugar de por archivo.

Grep es la herramienta principal aquí. Busca archivos sospechosamente cortos, archivos sin encabezado alguno, referencias a imágenes no resueltas, marcas entre corchetes que indican un vacío de análisis y caracteres de reemplazo que indican un problema de codificación. Cada una de esas búsquedas revela una clase de falla en segundos.

Agrega automatización al flujo de trabajo mientras lo haces: un verificador de enlaces para detectar referencias internas rotas, un validador de metadatos si tu generador lo requiere, y un paso de compilación que falle si faltan imágenes. Una vez que esos pasen, el archivo tiene la misma calidad que tu documentación mantenida.

Donde Markdown es el objetivo incorrecto

Markdown deliberadamente no puede expresar un diseño complejo de página, y algunos documentos Ami Pro fueron diseñados más que escritos — boletines, formularios formateados, portadas de informes con composición basada en marcos. Forzar esos en Markdown produce algo técnicamente válido y prácticamente inútil.

Lo mismo se aplica a los documentos cuyo significado es legal y depende de una presentación exacta: contratos ejecutados, formularios firmados, avisos oficiales. Para esos, PDF es el resultado honesto, y si quieres que sean descubribles junto con Markdown, conviértelos a ambos y vincula el PDF desde un pequeño resumen Markdown.

Ser selectivo no es un compromiso. Un repositorio de documentos lleno de Markdown limpios y estructurados, más un conjunto vinculado de PDF para documentos que necesitan un diseño fijo, es un resultado mejor que un montón uniforme de conversiones degradadas.

Qué aporta Markdown a un archivo antiguo

Historial de versiones, revisión y comparaciones para documentos que nunca los tuvieron
Publicable con el mismo generador de sitios estáticos que la documentación actual
Archivos de texto plano pequeños y portátiles que sobreviven a cualquier herramienta concreta
Estructura de encabezados apta para índices y para la fragmentación con IA
Ecuaciones en LaTeX que siguen siendo buscables en lugar de convertirse en imágenes

Los documentos heredados merecen herramientas modernas

La brecha entre un archivo .sam y un archivo Markdown en un repositorio no es solo un cambio de formato. Es la diferencia entre contenido que nadie puede inspeccionar y contenido que participa en la revisión, búsqueda y publicación automatizada como todo lo demás que escribe tu equipo.

Confirma las hojas de estilo, decide tus convenciones de activos y ecuaciones antes de empezar, convierte el archivo en una sola pasada y revisa mediante grep en lugar de leyendo. Luego envíalo por el mismo proceso que el resto de tus documentos.