Cuaderno de Jupyter a Markdown: quedarse con el relato y tirar el envoltorio
Un cuaderno son dos documentos bajo un mismo nombre de archivo. Está lo que escribiste — títulos, explicaciones, código, el resultado impreso que demostraba algo — y está el sobre JSON en el que el formato lo guarda. Abre un .ipynb en un editor de texto y lo que ves es el sobre: cada línea de prosa aislada en su propia cadena, "execution_count": 7 en cada celda, objetos "metadata": {} vacíos por todas partes, y en algún punto un cuarto de megabyte de base64 que se dibuja como un pequeño diagrama de dispersión.
Convertir a Markdown tira el sobre y se queda con el documento. Tus celdas markdown ya eran Markdown, así que pasan intactas. Las celdas de código se vuelven bloques delimitados etiquetados con el lenguaje del kernel, la forma que ya entienden todos los modelos, todos los README y todos los generadores de sitios estáticos. Suelta un .ipynb arriba y la conversión ocurre en esta pestaña: el archivo nunca se sube.
Dónde está de verdad el peso
Se supone que un cuaderno grande es grande por el código. Casi nunca lo es. El peso vive en cuatro sitios, de mayor a menor:
- Las imágenes de salida en base64. Cada
plt.show()escribe el PNG renderizado dentro del archivo, en base64. Una figura son habitualmente 200 a 400 KB de caracteres. Un cuaderno con una docena de gráficos es sobre todo gráficos. Nada de eso significa nada para quien lee el texto. - Las representaciones HTML de los dataframes. Pandas emite tanto
text/plaincomotext/htmlpara el mismo resultado. La versión HTML arrastra estilos en línea y una<table>con una etiqueta por celda: puede pesar veinte veces la versión en texto plano y decir exactamente lo mismo. - Los fotogramas de las barras de progreso. Un bucle de tqdm escribe una línea nueva en cada refresco, separadas por retornos de carro. El archivo acaba con cientos de copias de una barra que solo se mostró una vez.
- Los metadatos por celda. Insignificantes de uno en uno, no en conjunto: identificadores de celda, contadores de ejecución, marcas de plegado y objetos de metadatos vacíos, repartidos por unos cientos de celdas, terminan sumando.
La conversión de arriba trata cada uno de estos casos. Las cargas multimedia se cuentan y se sustituyen por una única línea de referencia, para que siga viéndose dónde había una figura. Cuando un resultado ofrece texto plano y HTML, gana el texto plano. Las secuencias de retorno de carro se reducen al estado final de la línea. Los metadatos desaparecen por completo. La herramienta informa de lo que ha quitado: el ahorro se ve, no se afirma.
Por qué los bloques delimitados importan más de lo que parece
Lo más útil que Markdown le hace a un cuaderno es marcar explícitamente la frontera entre prosa y código. En el JSON crudo esa frontera solo existe como un campo "cell_type" situado varias líneas por encima del contenido. Aplanado sin cuidado, una explicación y el código que describe se juntan, y hay que deducir cuál es cuál solo por la sintaxis, seas persona o modelo.
Un bloque delimitado etiquetado con el lenguaje quita esa adivinanza. También arrastra el lenguaje del kernel: el conversor lee language_info de los metadatos del cuaderno, con respaldo en el kernelspec, de modo que un cuaderno de R o Julia queda etiquetado como R o Julia en vez de rebautizado en silencio como Python. Las salidas reciben su propio bloque sin etiqueta bajo la celda que las produjo, precedido de una simple línea Output:, lo que mantiene visible la relación de causa y efecto sin inventar una sintaxis que Markdown no tiene.
Las trazas de error merecen conservarse
Tienta borrar la salida de errores junto con todo lo demás. Suele ser la decisión equivocada. Si le entregas un cuaderno a un modelo y le preguntas por qué falla una celda, la traza es la pregunta entera. Lo que hace desagradables a las trazas en crudo no es el contenido sino los códigos de color ANSI con los que IPython las envuelve: secuencias de escape que se ven como color legible en una terminal y como galimatías ESC[0;31m en cualquier otro sitio.
Esas secuencias se quitan y el texto de la traza se conserva. Las largas se acortan por el medio y no por el final, porque en una pila profunda los marcos útiles son los primeros y los últimos, y las doscientas líneas de interioridades de biblioteca que hay entre ellos son justo lo que te habrías saltado.
Cuadernos dentro de un volcado de repositorio
La misma conversión corre dentro de las herramientas de GitHub, GitLab y carpeta local de este sitio. Selecciona un .ipynb en un repositorio y aterriza en la salida como celdas legibles y no como un muro de JSON. Esto importa más de lo que suena: en un repositorio de ciencia de datos los cuadernos suelen ser donde vive el razonamiento, y hasta ahora eran los archivos que había que desmarcar para que la salida siguiera siendo utilizable.
En ese contexto el límite de salida es más estrecho que en esta página, porque un volcado de repositorio es contexto para un modelo y las salidas de celda son su parte menos rentable por token. Una nota en el texto convertido registra cuánto se ha quitado: nada desaparece en silencio.
Los cuadernos antiguos siguen funcionando
La versión 4 del formato pone las celdas en un array cells de primer nivel. La versión 3, todavía repartida por repositorios públicos de principios de los 2010, las anida un nivel más abajo dentro de worksheets y llama al campo fuente input en lugar de source. Ambas formas se leen. También el tipo de salida pyout que usaba la versión 3 donde la 4 dice execute_result.
Hay dos cosas que deliberadamente no se intentan. Los widgets de cuaderno — deslizadores y gráficos interactivos apoyados en ipywidgets — guardan su estado en un bloque de metadatos aparte y no dan nada útil como texto; la referencia te avisa de que había uno. Y el orden de ejecución de las celdas se conserva tal como aparece en el archivo, sin ordenar por contador de ejecución: el orden en el que se lee un cuaderno es aquel en el que está escrito.
No se sube nada
Los cuadernos arrastran cosas que uno olvida: una clave de API pegada en una celda durante una depuración, una cadena de conexión a la base de datos, un trozo de datos de producción impreso para comprobar una unión. La conversión corre en JavaScript en esta pestaña. No hay paso de subida, ni copia en un servidor, ni nada cuya eliminación haya que pedir después. Cierras la pestaña y se acabó.
Si prefieres texto plano en vez de Markdown — sin bloques, sin estructura, solo la prosa y el código — el conversor de cuaderno a texto produce eso, y el archivo que has seleccionado te acompaña.