Mi forma de usar el práctico mdbook - con doctoc -
Hola, soy un inútil.
La usabilidad de mdbook, que se puede escribir en formato Markdown y es utilizado oficialmente por Rust para la creación de documentos incluso en el trabajo, es muy buena, así que presentaré cómo lo uso en mi caso.
Instalación
Instalar con cargo install
cargo install mdbook
Instalaremos doctoc para la generación de la tabla de contenidos que usaremos más adelante.
sudo npm -g install doctoc
Para ser honesto, probablemente hay otros comandos que pueden generar automáticamente una tabla de contenidos en Markdown, pero me falta investigación.
Configuración inicial
Simplemente ejecuta mdbook init
~/git/lets-mdbook$ mdbook init
Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...](alleycat:[haturatu]:~/git/lets-mdbook$ mdbook init
Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content
All done, no errors...
alleycat:[haturatu]:~/git/lets-mdbook$ ls
book book.toml src
Aquí, si colocas los archivos .md que serán los artículos en src, y los construyes, se generarán por defecto en el directorio book.
alleycat:[haturatu]:~/git/lets-mdbook/src$ ls
SUMMARY.md chapter_1.md](alleycat:[haturatu]:~/git/lets-mdbook$ cat src/
SUMMARY.md chapter_1.md
alleycat:[haturatu]:~/git/lets-mdbook$ cat src/SUMMARY.md
# Summary
- [Chapter 1](./chapter_1.md)
En este src/SUMMARY.md, puedes crear una tabla de contenidos que se mostrará en la barra lateral.
Automatizar el proceso de construcción con un script de shell y crear un historial de actualizaciones
Cada vez que actualizaba el directorio src, ejecutaba el comando doctoc y luego mdbook build... Pensé que era una tontería hacer algo tan estúpido... y no pude soportarlo más, así que creé un script de shell para poder ejecutar la serie de operaciones incluso mientras tenía vim abierto.
#!/bin/bash
pwd | grep "src$" || cd src
doctoc .
sed -i "3d" ./*.md
sed -i "/](\#/d" ./SUMMARY.md
sed -i "8a`date`" ./update.md
cd ..
mdbook build
git add .
git commit -m "wip"
git push
Esto significa que con pwd | grep "src$" || cd src, si src está incluido en el resultado de pwd, no se hace nada. Si no, se mueve a cd src.
La razón por la que hago esto es porque si ejecuto este script con :!../build.sh mientras edito src/*.md, se haría un cd dentro del directorio src, lo cual se siente un poco extraño, así que lo hago de esta manera. Bueno, no hay ningún problema con su funcionamiento incluso si no lo hago...
Además, se asume que git remote-url ha sido configurado y se ha hecho un git push al menos una vez, y update.md tiene este aspecto.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Update Log](#update-log)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Update Log
2024年 11月 23日 土曜日 22:39:24 JST
Con sed -i "8adate" ./update.md, se deja un registro de cuándo se ejecutó este script en la línea 8.
Para ser honesto, si se hiciera correctamente, sería mucho más conveniente y amable registrarlo en el historial de actualizaciones solo cuando hubiera un commit, determinándolo a partir del valor de retorno de git commit, pero por favor, comprenda que este fue un script improvisado...
¿No sería mejor usar Github Actions?
Este proceso de construcción puede ser utilizado con Actions.
Sin embargo, ¿qué pasa si el entorno no permite usar otros activos yml con uses?
Podría estar bien si se usa solo con Github Actions, pero si se usa GitLab como servidor Git, intentar usar los activos de github.com parece complicarse un poco (bueno, eso es de esperar...). Por eso lo hice de esta manera.
De hecho, la versión Enterprise de Github es bastante problemática en este aspecto...
Acerca del uso de acciones en su empresa
Así que pensé que no era muy fiable... y por eso yo, una persona aún menos fiable, lo escribí en un script de shell...