Meu uso conveniente do mdbook - com doctoc -
Olá, sou um incompetente.
O mdbook, que pode ser escrito no formato Markdown e é usado oficialmente pelo Rust para a criação de documentos no trabalho, é muito agradável de usar, então vou apresentar como eu o uso.
Instalação
Instale com cargo install
cargo install mdbook
Para a geração de sumário que usarei mais tarde, instalarei o doctoc.
sudo npm -g install doctoc
Para ser honesto, parece que existem outros comandos que podem gerar sumários automaticamente em Markdown, mas minha pesquisa é insuficiente.
Configuração Inicial
Basta executar 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
Aqui, ao colocar arquivos .md que serão os artigos em src e construir, o resultado será gerado por padrão no diretório 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)
Neste src/SUMMARY.md, você pode criar um sumário que será exibido na barra lateral.
Automatizando o processo de construção com um script shell e criando um histórico de atualizações
Toda vez que eu atualizava o diretório src, eu estava fazendo coisas estúpidas como executar o comando doctoc e depois mdbook build... achei que era uma tolice. Eu mesmo pensei isso e não aguentei mais, então criei um script shell para executar a série de operações mesmo enquanto o vim está aberto.
#!/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
Isso significa que com pwd | grep "src$" || cd src, se src estiver incluído no resultado de pwd, nada é feito. Caso contrário, ele se move para cd src.
A razão para fazer isso é que se eu executar este script com :!../build.sh enquanto edito src/*.md, ele faria cd dentro do diretório src, o que me incomoda um pouco, então fiz assim. Bem, não há problema funcional se eu não fizer isso, mas...
Além disso, assume-se que git remote-url foi configurado e um git push foi feito uma vez, e update.md está assim.
<!-- 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
Com sed -i "8adate" ./update.md, o log de quando este script foi executado é adicionado na linha 8.
Para ser honesto, se fosse feito corretamente, seria obviamente mais amigável se fosse determinado a registrar no histórico de atualizações apenas quando houvesse um commit a partir do valor de retorno de git commit, mas como foi um script improvisado, peço sua compreensão...
Não seria melhor usar o Github Actions?
Este processo de construção pode realmente ser usado com Actions.
No entanto, e se o ambiente não permitir o uso de outros ativos yml com uses?
Pode ser bom se for usado apenas com Github Actions, mas se você estiver usando GitLab como servidor Git, tentar usar os ativos de github.com parece ficar um pouco complicado (o que é compreensível...). Por isso, fiz como descrito aqui.
Na verdade, a versão Enterprise do GitHub é bastante problemática nessa área...
Sobre o uso de Actions no Enterprise
Então, pensei que não poderia depender muito disso... e por isso, eu, que sou ainda menos confiável, escrevi no script shell...