mdBook e integración de repositorios de código y wikis
Hoy nos ocuparemos del microwiki.
La idea es que tengamos un sitio web donde podamos colocar nuestra memoria en línea y hacerla disponible a nosotros y otros interesados.
Para ello usaremos mdBook:
Instalación
Para verificar que está instalado, desde la terminal escribimos:
c
Y debería aparecernos algo como esto:
Creates a book from markdown files
Usage: mdbook.exe [COMMAND]
Commands:
init Creates the boilerplate structure and files for a new book
build Builds a book from its markdown files
test Tests that a book's Rust code samples compile
clean Deletes a built book
completions Generate shell completions for your shell to stdout
watch Watches a book's files and rebuilds it on changes
serve Serves a book at http://localhost:3000, and rebuilds it on changes
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
For more information about a specific command, try `mdbook <command> --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook
En caso de NO estar instalado debe aparecer un error. Si así, procedemos con el siguiente proceso de instalación.
Instalación en Windows
Abrimos la consola de comandos y desde Scoop instalamos mdBook.
Cuando terminamos la instalación, deberíamos ver algo como esto:
Installing 'mdbook' (0.4.44) [64bit] from main bucket
mdbook-v0.4.44-x86_64-pc-windows-msvc.zip (4,1 MB) [==========================================================] 100%
Checking hash of mdbook-v0.4.44-x86_64-pc-windows-msvc.zip ... ok.
Extracting mdbook-v0.4.44-x86_64-pc-windows-msvc.zip ... done.
Linking ~\scoop\apps\mdbook\current => ~\scoop\apps\mdbook\0.4.44
Creating shim for 'mdbook'.
'mdbook' (0.4.44) was installed successfully!
Instalación en Linux
Para Arch/Manjaro Linux y sus derivados hacemos:
yay -S mdbook
Creando nuestro primer libro
Desde la consola de comandos nos ubicamos en el directorio donde queremos crear el libro:
mkdir -p Documents/Repositorios
cd Documents/Repositorios
y escribimos el comando que inicializa el libro:
mdbook init LabCI
Nos hará preguntas interactivas desde la consola de comandos,
similares a estas:
Do you want a .gitignore to be created? (y/n)
n
What title would you like to give the book?
Wiki LabCI
2025-02-05 14:38:14 [INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...
Si vemos lado a lado la consola y el navegador de archivos, el resultado se vería como:
Vamos a navegar la carpeta recien creada:
Estas carpetas son:
book/: que es donde se aloja el resultado de libro web. Esta es la salida de informaciónsrc/: el donde están los documentos que generan el libro. Esta es la entrada de informaciónbook.toml: es el documento donde se configura el libro como tal.
Revisemos ese último archivo.
Pero antes, instalemos lite-xl desde Scoop.
Al final del procedimiento deberíamos ver algo como:
Checking repo... OK
The versions bucket was added successfully.
PS C:\Users\lab-info\Documents\Repositorios> scoop install versions/lite-xl-addons
Installing 'lite-xl-addons' (2.1.7) [64bit] from 'versions' bucket
lite-xl-v2.1.7-addons-windows-x86_64.zip (2,0 MB) [===========] 100%
Checking hash of lite-xl-v2.1.7-addons-windows-x86_64.zip ... ok.
Extracting lite-xl-v2.1.7-addons-windows-x86_64.zip ... done.
Linking ~\scoop\apps\lite-xl-addons\current => ~\scoop\apps\lite-xl-addons\2.1.7
Creating shim for 'lite-xl'.
WARN Overwriting shim ('lite-xl.exe' -> 'lite-xl.exe') installed from lite-xl
Making C:\Users\lab-info\scoop\shims\lite-xl.exe a GUI binary.
Creating shortcut for Lite XL (lite-xl.exe)
'lite-xl-addons' (2.1.7) was installed successfully!
Abrimos Lite-XL y desde allí abrimos book.toml
[book]
authors = ["Offray Luna", "Marilyn Caro", "Andrés Becerra"]
language = "es"
multilingual = false
src = "src"
title = "Wiki LabCI"
Poblando de contenidos el wiki
Lancemos el mdbook con las opciones por omisión de la configuración
y ahora, dentro de book creemos una subcarpeta llamada autoformacion
mkdir -p book\autoformacion
Vamos a adescargar dentro de la subcarpeta autoformacion, las memorias de las sesiones.
Empezando con esta sesión y yendo hacia atrás:
Al final tendremos algo como:
|_ LabCI/
|_ book.toml
|_ book/
|_ autoformacion/
|_ 15.md
|_ 14.md
|_ 13.md
Veremos cómo se verían estos contenidos en la web.
Nos dirigimos a la carpeta LabCI y escribimos:
mdbook serve --open
Veremos algo como:
Lo importante es que se ha generado un archivo plantilla titulado src/SUMMARY.md, que contiene la tabla de contenidos de nuestro posible libro.
Modífiquemoslo para que luzca como:
# Summary
- [Capítulo 1](./chapter_1.md)
- [Autoformación](./autoformacion.md)
- [Sesión 15](./autoformacion/15.md)
Y peguemos en el documento reciencien creado, los contenidos del documento que descargamos.
Importante: comentemos los metadatos de YAML para que no generen ruido en la versión de mdBook.
Deberían lucir algo como:
<!--@yaml
---
breaks: false
tags: LabCI, autoformación
---
-->
Y salvamos. Si vemos el documento en nuestro computador, debería lucir como:
Reconfiguración de mdBook y depuración de errores
Nos ubicamos desde la terminal en la carpeta donde creamos nuestro libro con mdbook:
Habitualmente lanzamos programas desde el menú de Windows:
Pero podemos lanzarlos desde la terminal:
lite-xl
Si lo lanzamos desde una ubicación en particular, por ejemplo la carpeta del libro, veremos también las subcarpetas y archivos que estan en esa ubicación.
Desde la terminal:
- Ubicarse en la carpeta del libro configurado en sesión anterior.
- Lanzar lite-xl.
Si comparamos el archivo de configuración con las subcarpetas creadas automáticamente por mdbook init,
nos daremos cuenta que la subcarpeta src/ corresponde al la configuración src = "src".
Entender esto es importante para entender los cambios que vienen.
Cambiemos la carpeta para que sea más diciente:
[book]
authors = ["Equipo LabCI"]
language = "es"
multilingual = false
src = "wiki"
title = "Wiki LabCI"
Modificar la carpeta del código fuente de nuestro libro por wiki,
como aparece en el ejemplo anterior.
Lancemos ahora nuestro servidor (vista web) del libro:
mdbook serve --open
2025-02-24 07:59:56 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in "C:\\Users\\lab-info\\Documents\\Repositorios\\LabCI\\wiki" directory
2025-02-24 07:59:56 [ERROR] (mdbook::utils): Caused By: El sistema no puede encontrar la ruta especificada. (os error 3)
Interpretemos el error en detalle:
-
mdbook serve --open 2025-02-24 07:59:56 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in "C:\\Users\\lab-info\\Documents\\Repositorios\\LabCI\\wiki" directory 2025-02-24 07:59:56 [ERROR] (mdbook::utils): Caused By: El sistema no puede encontrar la ruta especificada. (os error 3)Este mensaje nos dice:
- cuando ocurre el mensaje
2025-02-24 07:59:56, - de qué naturaleza es:
[ERROR] - detalles del mismo:
Error: Couldn't open SUMMARY.md in "C:\\Users\\lab-info\\Documents\\Repositorios\\LabCI\\wiki" directory
- cuando ocurre el mensaje
Renombrar la carpeta src por wiki para hacerla consistente con el archivo de configuración.
Desde de interfaz gráfica se haría así:
O desde la terminal:
mv src wiki
Si relanzamos ahora el libro veremos que no hay ningún error:
mdbook serve --open
2025-02-24 08:08:29 [INFO] (mdbook::book): Book building has started
2025-02-24 08:08:29 [INFO] (mdbook::book): Running the html backend
2025-02-24 08:08:30 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
2025-02-24 08:08:30 [INFO] (mdbook): Opening web browser
2025-02-24 08:08:30 [INFO] (warp::server): Server::run; addr=[::1]:3000
2025-02-24 08:08:30 [INFO] (warp::server): listening on http://[::1]:3000
2025-02-24 08:08:30 [INFO] (mdbook::cmd::watch::poller): Watching for changes...
Démonos cuenta de qué naturaleza son los nuevos mensajes:
son mensajes de información que nos muestran qué está pasando con el libro.
Notemos el último mensaje en particular:
2025-02-24 08:08:30 [INFO] (mdbook::cmd::watch::poller): Watching for changes...
Revisémos en detalle de qué va sese Watching for changes... (atento a los cambios).
Para ello vamos a editar un archivo de ejemplo (creado automáticamente por mdbook init) en la subcarpeta que hemos renombrado como wiki/
Entrar a la subcarpeta wiki/ y abrir el archivo chapter_1,
modificándolo a nuestro acomodo.
Creación de tablas de contenido
Detengamos el servidor.
Para ello nos paramos en la terminal donde se está ejecutando y presionamos la combinación de teclas
Ctrl + C
Con el servidor de mdbook detenido, ubiquémonos en el archivo SUMMARY.md.
Su contenido es este:
# Summary
- [Chapter 1](./chapter_1.md)
Si miramos en detalle se trata de una lista que apunta a direcciones del disco duro en la carpeta local.
Esto se reconoce porque dichos enlaces empiezan por ./,
por ejemplo ./chapter_1.md.
Vamos a extender esa tabla de contenidos para que de cuenta de los trabajos que llevamos hasta el momento.
Para ello usaremos la documentación oficial de mdBook sobre tablas de contenido.
Si notamos el ejemplo al final, notaremos una correspondencia entre el cógido fuente de la tabla de contenido en el archivo SUMMARY.md y lo que se muestra en el documento.
Vamos a convenir una tabla de contenido similar, pero para nuestro portafolio personal.
# Summary
- [Presentación](./presentacion.md)
# Sesiones
- [Micrositios de documentación y publicación (parte 2)](unisemanticas/sesiones/25A9.md)
# Portafolio
# Caja de herramientas
Si relanzamos el servidor, veremos lo siguiente:
IMPORTANTE: Mientras se está editando el archivo SUMMARY.md no se debe tener funcionando el servidor de mdbook.
De lo contrario, en la medida en que se edita el archivo SUMMARY, se van a ir creando archivos temporales que corresponde a esas ediciones.
- Las listas de la tabla de contenido deben usar caracteres consistentes (
-,*). - Los nombres de los archivos a los que se apunta, no deben contener espacios.
Desde la terminal:
-
nos ubicamos en la subcarpeta donde tenemos inicializado nuestro libro
-
desde allí relanzamos
lite-xl, -
nos ubicamos en el archivo
SUMMARY.md(que deberá muy seguramente estará preseleccionado) -
lo editamos para actualizar la tabla de contenido de la siguiente manera:
# Summary - [Presentación](./presentacion.md) # Sesiones - [Micrositios de documentación y publicación (parte 2)](unisemanticas/sesiones/25A9.md) # Portafolio - [Ejercicio de Markdown](unisemanticas/portafolio/markdown.md) - [Mapa mental de AlexNet](unisemanticas/portafolio/alexnet.md) - [Estrategias metacognitivas](unisemanticas/portafolio/metacognitivas.md) - [Podrá el código abierto cambiar la democracia](unisemanticas/portafolio/shirky.md) # Caja de herramientas -
Salvamos el archivo
SUMMARY.mdy relanzamos el servidor de mdbook (mdbook serve --open) veremos la tabla de contenidos actualizada:
-
Terminamos el servidor yendo a la consola y presionando la combinación de teclas
Ctrl+c.
Poblando contenidos de la tabla
Notaremos que una vez tenemos la tabla de contenido y lanzamos el servidor, nuestro sistemas de archivos refleja esa tabla de contenidos creando las subcarpetas y archivos dentro de ella.
Esto también se refleja en la jerarquía de archivos y carpetas mostrada por lite-xl.
-
Desde
lite-xlcliqueamos algunos de los archivos.
Importante: elegir alguno de los archivos del portafolio,
si bien este ejemplo se hará con la caja de herramientas. -
Copiar y pegar alguno de los contenidos del portafolio propio a esas archivos.
En caso de que lo que copiemos y peguemos tenga metadatos de YAML, debemos comentarlos de manera similar a esta:
<!--@meta --- breaks: false tags: unidades semánticas, LabCI, MAI3 --- --> -
Relanzamos el servidor de mdbook, en caso de no estar funcionando, desde la terminal y si visitamos en enlace dentro de la tabla de contenido que corresponde al archivo que acabamos de editar deberíamos ver su contenido:
