我使用mdbook的便捷方式 - 附带doctoc -

4 min

mdbookgithubシェルスクリプトbash
language: ja bn en es hi pt ru zh-cn zh-tw

你好，我是个无能的人。
在工作中，我发现mdbook（它允许以Rust官方使用的Markdown格式编写文档）非常好用，所以我想介绍一下我的使用方法。

安装

使用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中可以创建显示在侧边栏的目录。
Image

使用Shell脚本自动化构建并创建更新历史

每次更新src目录时，都要运行doctoc命令，然后mdbook build... 这种愚蠢的操作让我觉得自己很傻。我实在受不了了，所以创建了一个shell脚本，即使在打开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 | grep "src$" || cd src的意思是，如果pwd的结果包含src，则不执行任何操作。如果没有，则移动到cd src。
我为什么要这样做呢？因为在编辑src/*.md时，如果使用:!../build.sh运行这个脚本，它会在src目录内执行cd，这让我感觉有点不舒服，所以才这样做了。不过，即使不这样做，操作上也没有任何问题。
另外，这假设已经设置了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中使用。
但是，如果在无法使用uses引用其他yml资产的环境中，情况会怎样呢？

如果只在Github Actions中使用，那可能没问题，但如果将GitLab用作Git服务器，尝试使用github.com的资产似乎会变得有点复杂（这也很正常……），所以我才采取了这种方式。
实际上，Github的企业版在这方面相当麻烦……。
关于在企业中使用Actions

所以，我觉得不能太依赖它……。于是，我这个更不可靠的人就把这些写进了shell脚本……。

Related Posts