I made a sitemap generator for mdBook. It was my first time releasing a crate!

I'm in high school in Japan. I'm afraid that this article may include some unnatural points.

Motivation

I'm creating a web document that explains systematically what programming is all about. I used mdBook, a static site generator written in Rust. However, I found it doesn't support Sitemap generation.

mdBook has a rich ecosystem to expand its functionality. Luckily I found mdbook-sitemap-generator that supports my project.

rxdn / mdbook-sitemap-generator

Utility to generate a sitemap.xml file for an mdbook project

mdbook-sitemap-generator

What is this?

mdbook-sitemap-generator is a simple utility to generate sitemap.xml files for mdbook projects.

Installation

Binaries are distributed on the Github Releases Page.

It is also possible to install this utility via cargo, using cargo install mdbook-sitemap-generator.

Usage

The utility should be run from the root of the project.

USAGE:
    mdbook-sitemap-generator [OPTIONS] --domain <DOMAIN>

OPTIONS:
    -d, --domain <DOMAIN>
    -h, --help               Print help information
    -o, --output <OUTPUT>

When running the utility, you must pass the site's domain on URL via the -d flag, for example, -d docs.example.com.

If the -o flag is not passed, the sitemap will be written to stdout.

For example:

$ ls
book  book.toml  src
$ mdbook-sitemap-generator -d docs.example.com -o book/sitemap.xml

View on GitHub

However, it doesn't support the latest version of mdBook. There was an alternative sitemap-generation backend but written in Go. We can't install it through cargo. So I decided to make my own alternative.

LLM Assisted Coding

I asked Claude Sonnet to generate a simple sitemap generator written in 100% Rust. The code claude made includes implementation and unit tests. The unit tests passed. However, there is one mistake in the JSON format that mdBook sends to the custom backend.

Manual Coding

I added to it simple CI flows for validating project and integration test that simulate the latest version of mdBook behavior. Thanks to this setup, I was able to notice it doesn't run correctly.

I read mdBook documents and found JSON form mismatch. I revised the code and check if the integration test pass.

trait Tester: Sized {
    fn init_book_toml() -> &'static str;

    fn init_mock_contents(src_dir: &Path);

    fn validate_sitemap(book_dir: &Path);

    fn run_test() {
        // 1. initialize virtual file system
        // 2. make virtual book.toml
        // 3. make src/ SUMMARRY.md and each sections
        // 4. run mdBook build
        // 5. validate generated sitemap.xml
    }
}

I made Tester trait and make it easy to add various integration tests. If you want to see concrete implementation, see github.

https://github.com/sonneko/mdbook-sitemap/blob/main/tests/mod.rs

How to use it

No complex configuration is required! Just install through cargo and add very simple configurations on your book.toml.

cargo install mdbook-sitemap

[output.sitemap]
base-url = "https://example.com/docs"

Conclusion

Please feel free to use mdbook-sitemap. I'd appreciate it if you would give it a star.

Github:

sonneko / mdbook-sitemap

Tool to generate a sitemap.xml file for an mdBook project

mdbook-sitemap

Tool to generate a sitemap.xml file for an mdbook project

This tool is an mdBook backend that automatically generates a sitemap.xml

file when mdbook build is run. It reads the book structure from stdin (as JSON provided by mdbook) and writes sitemap.xml to the output directory.

Usage

1. Install mdbook-sitemap

cargo install mdbook-sitemap

2. Add config to your Book.toml

[output.html]

[output.sitemap]
base-url = "https://example.com/docs/"
# Optional settings:
# change-freq = "weekly"          # always|hourly|daily|weekly|monthly|yearly|never
# priority = 0.7                  # 0.0 - 1.0
# output-filename = "sitemap.xml" # output filename
# include-draft = false           # whether to include draft chapters

Licence

MIT license

View on GitHub

Crates.io
https://crates.io/crates/mdbook-sitemap