Publish a website/book for this config
foo-dogsquared opened this issue · comments
The documentation on this project is getting bigger (not all are part of the publicly pushed changes though). Just for the running theme of being an overkill NixOS config, it would be appropriate to have a website/book on this config alone. It also gives me a chance to other SSGs.
Here's what I've scouted so far:
As fallback, I could always use Hugo with Asciidoctor.
(By the time this is posted, I've already done some scaffolding with Hugo but this is something I've written yesterday.)
- mdBook, while nice and easy to setup for writing up project documentations from the ground up, is not appropriate for the running theme of customized overkill. More importantly, it uses Markdown as the primary markup text format and while it can be extended with custom processors, it isn't enough for my case.
- mkDocs (specifically Material for MkDocs) is an overkill with a nice set of quality features for the reader. But still not appropriate enough for the customized overkill.
- Gatsby can be overkill and has a vast ecosystem of extensions for me to use including adding support for Asciidoctor markup. Unfortunately, it uses Node.js and npm which is not great to use so it's-a-nada.
- Antora is considered. While nice with its out-of-the-box features such as the versioning of multiple sources and the native support of Asciidoctor markup format, I discarded considering I'm not familiar with it yet. Also, it uses Node.js and npm.
Good ol' Hugo with Asciidoctor indeed then.
It's now live at https://foo-dogsquared.github.io/nixos-config/.