Para quién es
Pasa documentación a Markdown sin limpiar
Migrar documentación suele significar convertir el HTML y luego pasar más tiempo quitando lo que el conversor decidió conservar. Ese recorte es justo para lo que se hizo Clean Clipper, y es la parte que está medida: cero etiquetas HTML sobrantes en las 512 páginas del corpus. Los encabezados, las listas, las tablas, los bloques de código y las notas al pie se corresponden con Markdown estándar.
La limpieza que come el día
Un conversor genérico convierte todo lo que encuentra, y una página de documentación es sobre todo envoltorio: barra lateral con el árbol completo, selector de versión, migas de pan, botones de «editar esta página» y un pie con cuatro columnas de enlaces. La conversión tarda un segundo; la limpieza, veinte minutos por página. Multiplicado por las páginas que haya que migrar, ahí es donde se va el calendario del proyecto.
Lo que se rompe además es la estructura. Los encabezados vacíos de los bloques de navegación se cuelan como secciones, los avisos y las llamadas de atención pierden su forma, y los bloques de código salen sin etiqueta de lenguaje, así que la documentación migrada aparece en gris. Corregirlo a mano es donde se va el proyecto.
Y antes de convertir nada está la pregunta que casi nadie responde: qué páginas hay que migrar. El mapa del sitio declara novecientas direcciones y de esas se leen sesenta; el resto son índices, redirecciones y versiones antiguas. Por eso aquí no hay rastreador, y no es una carencia: capturar página a página obliga a decidir qué entra, y esa decisión tomada al principio es la que evita importar ochocientas páginas que nadie va a revisar.
Qué cambia en la migración
- Encabezados, listas, tablas, bloques de código y notas al pie se corresponden con Markdown estándar
- Las etiquetas de lenguaje se conservan en los bloques de código
- Cero etiquetas HTML sobrantes en las 512 páginas medidas
- Las barras laterales y los selectores de versión se cortan, no se convierten
- Los encabezados vacíos, artefacto habitual de la navegación, se descartan
- La plantilla de nombre y la subcarpeta mantienen ordenado un conjunto importado
- Las llamadas de atención se convierten en citas, porque Markdown no tiene una sintaxis estándar para ellas
- Los enlaces internos se conservan como direcciones absolutas al sitio de origen: nada se reescribe a ciegas
## 4.4. Sentencias break y continue
La sentencia `break` termina el bucle `for` o `while` que la contiene.
```python
for n in range(2, 10):
for x in range(2, n):
if n % x == 0:
print(n, "es igual a", x, "*", n // x)
break
```
| En la página | En la nota |
| --- | --- |
| `<h2>` del cuerpo | `##` |
| `<div class="admonition">` | cita con `>` |Cómo migrar documentación paso a paso
El orden de este trabajo importa más que la herramienta: primero se decide qué se migra y después se convierte. Estos siete pasos siguen ese orden.
- Antes de configurar nada, haz la lista de páginas que de verdad hay que migrar. El mapa del sitio no sirve como lista: incluye índices, redirecciones y versiones antiguas que nadie consulta.
- En los ajustes, elige como carpeta de destino el directorio del repositorio donde vivirá la documentación, y escribe la subcarpeta del conjunto que estás importando. Trabajar directamente contra el repositorio evita el paso de mover archivos desde Descargas.
- Pon la plantilla de nombre en
{title}. En una migración, el nombre del archivo acabará siendo la dirección de la página nueva, y una fecha delante estorba; los caracteres que el sistema de archivos no admite se sustituyen solos. - Deja activo el campo
sourceen el frontmatter. Durante toda la migración es la única forma barata de volver a la página original para comprobar algo, y al terminar se borra con una pasada. - Antes de capturar cada página, deja en pantalla lo que quieras conservar: la pestaña de ejemplos que corresponda, las secciones plegadas abiertas y el selector de versión en la versión correcta. Se convierte lo que hay en el DOM en ese instante.
- Captura las tres o cuatro primeras páginas y revísalas antes de seguir. Si en ese sitio las admoniciones, las tablas y los bloques de código llegan como esperas, llegarán igual en las demás: lo que varía entre páginas es el contenido, no el marcado.
- Al terminar, pasa por el conjunto una revisión de enlaces internos. Se conservan como direcciones absolutas al sitio de origen, porque la extensión no sabe dónde vivirá cada página en el destino; reescribirlos es un paso tuyo, y hacerlo con una regla es rápido cuando todos apuntan al mismo dominio.
Ajustes para una migración
La configuración de abajo está pensada para importar decenas de páginas seguidas con el mismo criterio. La diferencia con el uso normal está en el nombre del archivo y en el destino.
| Ajuste | Valor | Por qué así en una migración |
|---|---|---|
| Clic en el icono | Carpeta | Con decenas de páginas seguidas, una ventana que cerrar por página se convierte en el cuello de botella |
| Carpeta de destino | El directorio del repositorio | Escribir directamente donde vivirá la documentación ahorra un paso de mover archivos por página |
| Plantilla de nombre | `{title}` | El nombre acabará siendo la dirección de la página nueva; una fecha delante habría que quitarla después |
| Frontmatter | `title`, `source` | `source` es la vuelta barata al original durante la migración, y se borra de una pasada al terminar |
| Imágenes | Enlace | Los diagramas no se descargan; el enlace deja localizado qué hay que recuperar del sitio antiguo |
| Subcarpeta | El conjunto que se importa | Mantiene separadas las tandas cuando la migración se hace por partes y en semanas distintas |
| Antes de capturar | Fijar versión, pestaña y secciones plegadas | Se convierte lo que está en el DOM: una pestaña cerrada no existe para la captura |
## Configurar la autenticación Antes de empezar, revisa los [requisitos previos](https://learn.microsoft.com/es-es/azure/requisitos). > **Importante** > Los cambios en la directiva tardan hasta 15 minutos en aplicarse a las > sesiones ya iniciadas. ```bash az account set --subscription "Producción" ``` La llamada de atención llega como cita: Markdown no tiene una sintaxis estándar de admonición, así que se conserva el contenido y no el estilo. El enlace interno se queda apuntando al sitio de origen, porque la extensión no sabe dónde vivirá esa página en el destino. Y el encabezado vacío que el sitio usa para anclar la barra lateral no aparece: los encabezados sin texto se descartan.
Tres casos reales
Decidir qué se migra antes de migrar
El sitio antiguo declara novecientas direcciones y el equipo pide una estimación. En lugar de convertirlo todo, recorres la documentación como la recorre un lector y capturas solo lo que tiene contenido propio: sesenta páginas en dos tardes.
Esa lista es la estimación, y además ya está convertida. Que no haya rastreador obliga a esa selección, y es lo que impide que la migración empiece con ochocientas páginas que nadie va a revisar. Cada captura tarda decenas de milisegundos; el tiempo se va en decidir, que es donde debe irse.
Una referencia de API con tablas de parámetros
La parte cara de una referencia son las tablas: parámetros, tipos, valores por defecto, códigos de respuesta, casi siempre con código dentro de alguna celda. La extensión escribe las tablas por su cuenta en lugar de apoyarse en un conversor genérico, y una celda con una lista o un ejemplo ya no parte la fila.
La medida está publicada: doce tablas conservadas de quince en el corpus técnico, frente a siete de cada motor comparado. Lo que no se resuelve son las celdas combinadas, porque Markdown no sabe expresarlas: el contenido se conserva y la combinación visual se pierde.
Traer documentación ajena al repositorio interno
Tu equipo depende de la documentación de un proveedor y quiere una copia dentro del repositorio, con su fecha y su origen. Capturas las páginas relevantes a la subcarpeta correspondiente, con source y published en el frontmatter.
Lo que obtienes es texto revisable en una petición de cambios, comparable entre versiones y buscable con las mismas herramientas que el código. La conversión no toca el contenido: en las 512 páginas del corpus no sobrevivió ni una etiqueta HTML dentro del Markdown, que es la métrica que decide cuánta limpieza queda por hacer.
Frente a las otras formas de migrar
Cuando existe una exportación del propio sistema de contenidos, esa suele ser el punto de partida correcto. Lo que sigue compara lo que se hace cuando no la hay, con esta extensión incluida.
| Cómo se hace ahora | Qué obtienes | Qué cuesta |
|---|---|---|
| Exportación del gestor de contenidos | El origen completo con su estructura y sus metadatos | No siempre existe ni hay acceso, y el formato exportado a veces necesita otra conversión |
| Conversor genérico de HTML a Markdown | Automatizable, rápido y repetible | Convierte todo lo que encuentra: barra lateral, selector de versión, migas de pan y pie; la limpieza posterior es el proyecto |
| Rastreador propio más un script | Cobertura total y control del proceso | Hay que escribirlo y mantenerlo, y sigue haciendo falta decidir qué páginas merecen la pena |
| Copiar y pegar página a página | Control absoluto sobre lo que entra | Se pierden las etiquetas de lenguaje y las tablas con código; veinte minutos por página |
| Guardar a PDF como respaldo | Un registro fiel del sitio antiguo | No sirve como origen para la documentación nueva: hay que volver a extraer el texto |
| Clean Clipper | Markdown estándar sin envoltorio, con las tablas y las etiquetas de lenguaje intactas | No rastrea, no reescribe enlaces internos, no descarga imágenes y convierte las admoniciones en citas |
Cuando la conversión no encaja
¿Por qué las llamadas de atención salen como citas?
Porque Markdown no tiene una sintaxis estándar para ellas. Cada generador de documentación usa la suya –directivas, contenedores con dos puntos, atributos propios–, y elegir una sería acertar en un destino y estropear los demás. Se conserva el contenido en forma de cita y el estilo lo pone el destino; convertir citas a la sintaxis de tu generador es una sustitución con expresión regular sobre el conjunto entero.
¿Por qué los enlaces internos apuntan al sitio antiguo?
Porque la extensión no sabe dónde vivirá cada página en el destino, y un enlace reescrito a ciegas es peor que uno que se sabe antiguo: el primero parece correcto. Se conservan como direcciones absolutas al origen, lo que además los deja localizables con una búsqueda por el dominio. La reescritura se hace al final, cuando ya existe la estructura nueva.
¿Por qué faltan algunos encabezados de la página?
Porque estaban vacíos. Los generadores de documentación insertan encabezados sin texto para anclar la barra lateral o el botón de «editar esta página», y convertirlos produce secciones fantasma en el árbol del documento.
Se descartan a propósito. Si echas en falta un encabezado que sí tenía texto, mira si formaba parte de la navegación: los bloques de navegación se cortan enteros, y un encabezado dentro de uno de ellos se va con el bloque.
¿Por qué no está el contenido de las pestañas?
Porque solo se convierte lo que hay en el DOM cuando pulsas. Los ejemplos repartidos en pestañas por lenguaje, las secciones plegadas y lo que carga al desplazarse no existen para la captura hasta que aparecen en pantalla. Abre la pestaña que quieras conservar y captura; si necesitas dos, captura dos veces y el sufijo numérico mantiene las dos copias en la carpeta.
Lo que no hace
No rastrea: no hay forma de decirle «tráete este sitio entero», y capturas página a página, las que quieres. No conserva las llamadas de atención como tales, porque Markdown no tiene una sintaxis estándar para ellas: se convierten en citas. No descarga las imágenes ni los diagramas, que quedan como enlaces al sitio original. Y no reescribe los enlaces internos: siguen apuntando al sitio de origen, no a las páginas migradas.