Just wanted to give a shoutout to Pietro Peterlongo, Regis Caillaud, and Hugo Granström for their great work on nimibook. I've just finished moving Norm docs from the built-in doc generator to nimibook and I have to say it was a lovely experience.
nimibook is just great. What I love about it most is that you write the docs in Nim, which gives you all the power Nim has. So, you can include text from external sources and it's trivial, you can format your text and so on and so on.
I think its potential is actually much larger than advertised on its site or in Pietro's NimConf presentation. I believe, because you can use actual Nim in the source, you can do most things other documentation generators achieve with extensions and more.
Great to hear you enjoyed it! đŸ˜„ Pietro really has created a really powerful and extensible framework for writing code and text in a great manner. You could do virtually anything you want with it without any boilerplate thanks to metaprogramming in Nim.
Regarding build times, yes it's quite slow atm. And it's the downside of its strength, namely that it is written in Nim and as such needs to be compiled and run compared to just parsing a markdown file which is the norm in these kind of tools. Ideally it should support two build modes: one for incremental changes where we just compile the modified files, and one where we rebuild the entire book (great for making sure that all of the code still runs).
It used to be exactly like this before the migration :-) It has its advantages but it has disadvantages as well. Splitting the source makes it easier to maintain the docs and I'd argue that the navigation is better with multiple smaller pages instead of a single big one.
What's lacking is search, that's for sure. With a single page you can just Ctrl+F most things but with multipage structure you have to rely on site-wide search, which is currently lacking in nimibook.
Looks great!
Regarding build times, yes they are an issue. Building a single file/page (when no changes in toc or book configuration), should already possible using correct compile options (could probably be made more ergonomic).
An idea I have for further improving build times would be to have a json be written when saving document and on later builds nimibook could render directly starting from the json. There are still a couple of things I want to do before trying this though.
Splitting the source makes it easier to maintain the docs and I'd argue that the navigation is better with multiple smaller pages instead of a single big one.
I doubt both.
For first reading splitted documents are a pain. Imagine the Nim manual splitted into a dozen tiny pieces. I think for that cases I would have never started using Nim at all. Later, when we have read the whole document already and want to check a special part, then split content may be ok. So maybe we should allow two views.
For writing the source, I also prefer one large document. I think all that splitting of very closely related content into dozen of separate files was invented when files where read from floppy disk and editors could keep only a few hundred lines of source code in RAM. For really large projects with well separated parts like a compiler with parser, lexer, various backends separation into multiple files makes sense of course.