After along slumber, Nimib is back with another update. For the average user who only use the builtin blocks (NbText, nbCode, nbImage etc) this doesn't bring any changes to your documents (fingers crossed!). But behind the scenes we have rebuilt Nimib's blocks and rendering from the ground up.
I will be hosting a talk about this update on NimConf 2026 for those that are interested.
The highlights are:
newNbBlock(NbImage):
url: string
caption: string
alt: string
toHtml:
&"""
<figure>
<img src="{blk.url}" alt="{blk.alt}">
<figcaption>{blk.caption}</figcaption>
</figure>
"""
template image*(url: string, caption = "", alt = "") =
let blk = newNbImage()
blk.url = nb.doc.relToRoot(url)
blk.caption = caption
blk.alt = if alt.len == 0: caption else: alt
nb.add blkThis does mean that if you have defined a custom block with custom rendering, it will have to be rewritten using the new structures. For more details and a migration example see the release notes: https://github.com/pietroppeter/nimib/releases/tag/v0.4.0
Congrats on the new release!
I'm a huge fan of Nimib and NimiBook, it's great that the project is alive and evolving.
If (when?) NimiBook adds site-wide search and a couple of convenience features, I'll be able to replace mdBook with it.
Really encouraging too hear ♥️ Hopefully with this release of of the way I should have some more motivation to work on new features.
I'll try to look into site-wide search during the summer. Any convenience features in particular you are thinking of?
I would say the mdBook preprocessors I use most commonly are mdbook-toc, mdbook-open-on-gh, and mdbook-admonish. Also mdbook-shiftinclude is nice.
However, I want to say that I hate mdBook's preprocessor system, it's a never ending dance of finding the right combination of mdBook version and the preprocessors versions that work together while echoing the least number of warnings. It's the functions that I need, not the plugin system.
For example, AFAIU we can achieve admonitions in NimiBook using custom block types without the preprocessor hacks (i.e. literally passing text through stdout between processes).
Thank you, I'll have a look at them :D
Yeah if it can be done using custom blocks that would be the optimal solution 👍
Celebrating the release with a bit of delay but today there is Nim Conf with a talk about this so I guess timing is not too bad.
Very happy with this release where the core work was the big NbBlock refactoring that started more than 2 years ago. Congrats to Hugo for bringing it home, great work!
Two sets of reasons why I am happy.
From technical point of view, I feel like the NbBlock type has finally been implemented right. It is now a base ref object of RootObj that supports building a hierarchy of custom object through inheritance (e.g. a base container object - was not possible before - or other objects with their custom field). I think inheritance is the right abstraction in this case and personally the path for this realization is for me a milestone in becoming a better programmer thanks to Nim. In the past the implementation details of NbBlock were not important and the user of the library was mostly shielded from it (on purpose). That is still true today. Nimib's traditional api (with nbCode: and similar blocks) is still the same, although we added a newer one (nb.code) that might be better (time will tell). In 0.1 the implementation was a very crude object with enum restricted variants and no possibility of custom blocks, 0.2 saw the adoption of custom blocks by strong coupling with mustache's Context, in 0.4 we removed this hard coupling (and we also added an automatic json backend). So technically there is a lot to be happy about.
But I am actually also happy about the social point of view, for various reasons these last few years I was able to dedicate little time to the project but, thanks to having a fellow maintainer in Hugo, we were able to keep it alive and running (even before 0.4 it was working fine) and managed to evolve it in an essential way. We will see what happens next, both from our work and possibly from people joining in. Thanks to all the contributors btw, we have always been lucky enough to have people contributing (to nimib, and to related projects, like nimibook and nimislides). Thanks also for everyone who shared their work built with nimib, that is always great motivation for us.
Have a great day everyone, Pietro