Мой способ использования удобного mdbook - с doctoc -
Здравствуйте, я бездарь.
Поскольку mdbook, который используется для создания документации в формате Markdown, официально используемом Rust, очень удобен в работе, я расскажу о том, как я его использую.
Установка
Установка с помощью cargo install
cargo install mdbook
Установите doctoc для генерации оглавления, которое будет использоваться позже.
sudo npm -g install doctoc
Честно говоря, вероятно, есть и другие команды для автоматической генерации оглавления в Markdown, но мне не хватило исследований.
Начальная настройка
Просто выполните 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
Здесь вы помещаете файлы .md, которые станут статьями, в каталог src, и при сборке они по умолчанию выводятся в каталог 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)
В этом src/SUMMARY.md вы можете создать оглавление, которое будет отображаться в боковой панели.
Автоматизация процесса сборки с помощью скрипта оболочки и создание истории обновлений
Каждый раз, когда я обновляю каталог src, я запускаю команду doctoc, затем mdbook build... Это казалось мне глупым, и я больше не мог этого терпеть, поэтому я создал скрипт оболочки, чтобы выполнять всю последовательность операций, даже когда я открываю vim.
#!/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
Это означает, что если результат pwd содержит src (pwd | grep "src$"), то ничего не происходит. Если нет, то переходим в cd src.
Причина, по которой я это делаю, заключается в том, что если я запускаю этот скрипт с помощью :!../build.sh во время редактирования src/*.md, он выполняет cd внутри каталога src, что немного неприятно. Хотя это не влияет на работу...
Предполагается, что git remote-url настроен и git push был выполнен хотя бы один раз, а update.md выглядит следующим образом.
<!-- 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
sed -i "8adate" ./update.md оставляет запись о запуске этого скрипта в строке 8.
Честно говоря, было бы гораздо лучше, если бы я проверял возвращаемое значение git commit и добавлял запись в историю обновлений только при наличии коммита, но это был импровизированный скрипт, поэтому, пожалуйста, примите это во внимание...
Почему бы не использовать Github Actions?
Эту задачу сборки можно фактически использовать с Actions.
Однако, что если среда не позволяет использовать другие ресурсы yml с uses?
Если использовать только Github Actions, это может быть хорошо, но если GitLab используется в качестве Git-сервера, попытка использовать ресурсы github.com может стать немного сложной (что, конечно, логично...). Поэтому я сделал это так, как описано.
На самом деле, корпоративная версия Github довольно проблематична в этом отношении...
Об использовании Actions в вашем Enterprise
Поэтому я подумал, что не стоит слишком на это полагаться... и написал это в скрипте оболочки, который еще менее надежен...