I’ve talked about my Rust project “lister” for the first time in this blog around 2 years ago, when I explained how to generate PDF files from individual Hugo entries. In the meantime I’ve enhanced it quite a bit, and this article provides some information about the latest version.
First, what is lister? It’s a small program written in Rust that takes as parameter the path to the folder containing all the source Markdown files of a Hugo website, reads the date field of each, and orders all entries by increasing date of publication, but only if the dates are earlier than today.
Why did I write it in Rust? Because this command must be used in Makefile and other scripts, and it has to be fast, fast, fast.
The program assumes that all Hugo source files are organized into individual folders, and within each folder, the main file is always named index.md. See the “fixtures” folder in this project (used for unit tests) for an example.
fixtures
├── fifth
│ └── index.md
├── first
│ └── index.md
├── fourth
│ └── index.md
├── second
│ └── index.md
└── third
└── index.md
And it’s fast! I have quite a few entries in this blog:
$ ls content/posts | wc -l
741
$ time lister content/posts
content/posts/jjj/index.md
content/posts/une-balade-sur-les-meilleurs-sites/index.md
content/posts/manuel-pratique-de-lutilisateur-dinternet-et-du-vms-à-sc2a.unige.ch-et-à-uni2a.unige.ch/index.md
content/posts/javascript-calculator/index.md
(...)
lister content/posts 0.00s user 0.01s system 95% cpu 0.013 total
Build
You can build the program using cargo:
$ git clone https://gitlab.com/akosma/lister.git
$ cd lister
$ cargo build --release
You can copy the final executable target/release/lister to any location in your $PATH.
Usage
To use the program, just pass the location of your Hugo source files as parameter:
$ lister content/posts
By default, this only prints the paths to the Markdown files whose date field are earlier than the date of execution, and orders all files from older to newer.
You can pass the -i or --invert option to return an inverted list, showing files from newer to older:
$ lister content/posts -i
Use the --start or -s option to specify a beginning date for the filter, and an --end or -e option to specify the end date. Dates must follow the format shown below:
$ lister content/posts --start "2004-01-01T00:00:00" --end "2018-12-31T00:00:00"
If you pass a --year or -y option, then the --start and --end arguments are ignored:
$ lister content/posts --year 2024
You can use the -v or --verbose option to display date information next to the filename.
Finally, the --help or -h option shows a help text:
Program listing Markdown files sorted by the "date" metadata field on the header
Usage: lister [OPTIONS] <PATH>
Arguments:
<PATH> (Mandatory) Path of the posts to parse
Options:
-i, --invert (Optional) Order results from the younger to older
-v, --verbose (Optional) Display date next to filename
-s, --start <START> (Optional) Used to start filtering; format is 2024-05-07T14:36:00
-e, --end <END> (Optional) Used to end filtering; format is 2024-05-07T14:36:00
-h, --help Print help
-V, --version Print version
All of this help functionality comes, of course, from the awesome clap crate.
Container
You can also use the prebuilt container image with podman or docker:
$ podman run --rm --volume "$PWD"/build registry.gitlab.com/akosma/lister:2.0.0 content/posts
The new container image is based on Alpine and it’s not even 10 MB! Check the Dockerfile for details.
Tests
Run all tests in the suite using this command:
$ cargo test
running 5 tests
test test_year_filter ... ok
test test_date_filter ... ok
test test_inverse_result ... ok
test test_wrong_date_filter ... ok
test test_normal_operation ... ok
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Documentation
Generate the documentation (and open it on a browser) with this command:
$ cargo doc --open