Creating mdbook-summary-maker - a summary.md automation tool

2023-05-12

Table of Contents

• Table of Contents
• Problem
• The solution
• Process
  • maybe a preprocessor?
  • hammering out my own preprocesor
  • here's when the bugs comes
  • Guess we are back to make the excutable.

Problem

The problem i want to solve has to do with my SUMMARY.md file. The method I use currenlty is to added the name of the file into SUMMARY.md whenever i'm writing a new post. I automated the process of adding new post a little bit when I was mirating everything into mdbook and netlify(detialed in this post), but it was still a semi-automatic expirence, which i'm aiming to improve. I want to be able to create a file, write in it, build the book and publishing it online without worrying about anything else.

The solution

Here is my repo. I ended up writing a excutable in rust that cycles through the folder

Process

maybe a preprocessor?

My first idea is to find already developed preprocessor. mdbook support these script that can be excuted before the content is sent in for rendering. After some searching, i found two possible solutions:

• mdbook-auto-gen-summary
• mdbook-fs-summary

I immediatly ditch the mdbook-fs-summary option because it requires me to rename all my files with number prefix, which is definitly a hassle i don't want to do.

After trying out the mdbook-auto-gen-summary, it only offers a mediocre solution. It doesn't provided with the desirable order I want to have with my SUMMARY.md, and it is not customizable.

So afterwards, I've decided to make a custom preprocessor myself.

hammering out my own preprocesor

In order to make my own preprocessor, I'm using the easy of of seeing how other people does it. So natrually, i went and look at the code of mdbook-auto-gen-summary, the preprocessor i was just looking at.

Upon first inspection, and some reading in mdbook's documentation, a few things stand out:

1. There is the framework called mdbook:preprocess that is for bulding custom preprocessor
2. The template

I then copied the file structure from mdbook-auto-gen-summary:

.
└── Project/
    ├── src/
    │   ├── your_mod_name/
    │   │   └── mod.rs
    │   └── main.rs
    └── cargo.toml

and implemented my own code in.

here's when the bugs comes

After testing out my preprocessor, I immediatly spotted some bugs:

• The SUMMARY.md generated seems to be stuck in a recursive loop. After the code generated the strucutre of the target folder and write it into SUMMARY.md, it would starting write in more of the same structure over and over again.
• IF the content of the SUMMARY.md was not cleared before running, some target would literatlly "explode", meaning that the content within the folder gets deleted, the files get dragged out of the target folder into its parent directory.

Then I realize the problem: I was aimming to update SUMMARY.md according the src/ folders current state each time i build the book. But the preprocessor can only manipulate the markdowns files the content files after SUMMARY.md gets loaded in, but before these files gets rendered. It cannot manipulate the SUMMARY.md file, then initiate the process of loading everything in and rendering.

That was not stated in any of the documentation! Thanks Rust!

Guess we are back to make the excutable.

So after finding this devastating fact, i went back and removed all the preprocessor framework, and instead code it like a script, exporting it to an executable, place the executable in the book folder, and added a line to my automation script here.