Hi all, I realized I never did officially announce the library 🐳nimib on the forum (although I did mention it multiple times since its beginning in November 2020).
Three weeks ago, we (me and @hugogranstrom) released a version 0.3 (codenamed BlockMaker) which reaches a big milestone in my vision for nimib, so I think this calls for a little celebration and a post on the forum.
First a brief introduction for those who have never heard of Nimib. It is a template based DSL that allows to transform nim code in a html document. The basic structure of a nim file using Nimib is as follows:
import nimib
nbInit # always needed to start a document
nbText: """# a title
put **markdown** text and it will be translated to html"""
nbCode: # code in a nbCode block is executed and output captured and rendered
let x = "hello"
echo x
# there are other blocks you can use
nbImage: ...
...
nbSave # with this block at the end Nimib will create a html document with the contents of all processed blocks
there are various examples in Nimib site linked above, and I started to collect random stuff in a blog (still in draft mode). A simple but nice example I did today is a plot of a function that looks like a plant: https://pietroppeter.github.io/nblog/drafts/trigonometric_plant.html
One of the feature I like the most of Nimib's default theme is the fact that in bottom right you have a Show source button that shows you the source used to produce the document. If you copy and paste that code in a example.nim file and run nim r example --nbShow you will see that a example.html file will be created and the browser will open to show it (this last thing thanks to --nbShow option).
So what is new in this 0.3 release? there are detailed release notes but the big milestone is the fact that Nimib is now able to easily produce interactive documents thanks to Nim's js backend. Basically we added a block that takes code, compiles it to javascript and writes the result in the html file. You can read more about how this works in this document and you can watch another example I just produced (a bouncing ball).
On top of that, we added a special template nbKarax to be able to reduce a little the boilerplate needed in order to create a Karax app. An example of this is this simple caesar app that implements caesar's cipher. Click show source to see the code and you can try to run it as mentioned above (you will need to install Nimib and Karax).
The above has been possible by a refactoring on the internal api and how the document is rendered. The result is that now is rather easy to create custom blocks for Nimib. Examples of this are:
Among other improvements, documents are now built automatically in CI and there is a preview generated when you open a PR. This should make contributing (and managing contributions) much easier. We also plan to use more the integrated github's forum to discuss and share stuff, so feel free to say hi there!
Last but not least, as I mentioned in the beginning, @hugogranstrom is joining me as maintainer of this library. Indeed, many (most) of the changes in this release are thanks to him. Thanks a lot Hugo ❤️ and welcome to the team 🥳!
ps: what will be next? there might be another announcement soon, and there is already a plan for what will be the next major breakage (a refactor of the rendering backend that should allow to easily add other backend). The idea for now is to have this release to settle, which means to fix stuff around, there are a ton of small improvements that can be made (contributions welcome!), but more than that: produce content with nimib. My personal number one priority though is to try and build a simple Static Site generator (similar to Jekyll, Hugo, ...) that will simplify the building of more complex sites. In particular I sorely need to have a decent theme for the nblog which I linked multiple times above.
It's a pleasure and honor to join the nimib team ♥️
Writing a Nim tutorial has never been easier than with Nimib. You can literally start with the finished program, divide it into code chunks in nbCode blocks and intersperse them with explainations in nbText blocks. And in the end you can be rest assured that the code you are showing actually works. Old outdated tutorials you don't realize have stopped working is now a thing of the past.
I'm looking forward to enjoying everyone's nimib content 😄
Congrats! Nimib and Nimibook are awesome, love using them to document Norm.
Did you ever faced an issue when the rendered documents have brackets and commas around text blocks? Check it out: https://norm.nim.town/ Maybe something changed in some version of Nimib? I have no clue why this happens. Locally, I get a proper build. On the CI, I get this.
❤️
I think it was solved in this PR but Nimibook 0.3 haven't been released yet. I think it's mainly documentation that is missing so it should be safe to use the latest commit. Could you try changing the dependency temporarily to nimibook@#head and see if that helps?
I can confirm everything that hugo said. It as in issue^ that should be present only with nimibook 0.2 and nimib 0.3 (in principle it should be reproducible locally but maybe it is due to some local templates not being updated -another changes in nimibook 0.3 is that templates will be loaded from memory). And I do need to release nimibook v0.3, I wanted to add a bit of docs, but if I do not manage (very likely) I will just tag and release before the holidays and document later.
^the issue is due to the fact that in nimib 0.3 we do not render blocks as a string (as in 0.2) but as a list, so in mustache template the content needs to change from:
{{{ blocks }}}
{{#blocks}}
{{&.}}
{{/blocks}}
Thanks! This did help. I had to update the configs here and there a bit but in general the update went smooth and painless. Great job!
Also, HUGE thank you for improving up the build time so much.
All in all, 0.3 is a really good update, loving it.
HUGE thank you for improving up the build time so much.
that is thanks to @ElegantBeef ;) https://github.com/pietroppeter/nimibook/pull/53