Hi!
First, some backstory.
I'm currently researching the potential options to replace mdBook in IFT's Nim projects. The reasons are:
These issues are not critical and we'll keep using mdBook unless something radically more ergonomic is found.
I think the a Nim-based tool for Nim projects would be a logical move so of course I'm looking in the direction of nimibook and Nim's built-in docgen
Nimibook is awesome but it still lacks some convenience features. The most important for me is that in order to unleash it's full potential, i.e. nbCode blocks and custom blocks, you have to write the docs in Nim files. This kills Markdown syntax highlighting in editors, requires imports and code that look cryptic for a newcomer (import nimib, nimibook; nbInit(theme = useNimibook; .... ; nbSave), and in general raises the bar for contributors. You can write the docs in plain Markdown but you can't use all the cool stuff that Nimibook offers this way.
Also, global search is missing which is a huge point whenever I'm comparing solutions.
I thinkg Nimibook is cool for personal projects but I don't have strong arguments to propose it as a replacement for mdBook just yet.
On the other hand, Nim compiler already ships with a built-in doc generator that uses a really nice flavor of Markdown, offers nice readable design with dark-mode and mobile support and global search.
The problem with it is that you either use nim md2html to turn a single Markdown file into a single HTML file which won't have global search or navigation or you use nim doc on .nim files to generate the docs from the doc comments. You can't have Markdown files organized as a book and use nim md2html to create a site out of it.
Or can you?
I've tried using hacks like creating a .nim file foo.nim with .. include:: foo.md and the actual content in foo.md. This way I can build the docs with nim doc and edit the content in Markdown, which is nice.
However, there are problems:
The docs are pretty sparse on this part of the compiler, so I thought maybe someone more experienced with the Nim doc generator could help me understand:
P.S. The one doc generator I really like is Foliant. Its superpower is that it uses unified XML syntax for syntax extensions so you don't have to memorize weird syntax for each new feature. I wrote it years ago in Python and it still works very well to this day. Running Python tools kind of sucks these days, the experience is similar to Rust as in you have to fight with the toolchain before you can do the actual writing. So despite my love for the project, I'd still prefer something Nim-based.
I built Nimony's website on nim md2html, take a look: https://github.com/nim-lang/nimony-website
Thanks, I'll check it.
Yeah, that was my point. :-)
I just wanted to save the next person some time. The "Y" in "FYI" is meant to be not you, Araq, but the next one reading :-)
BTW with very little hacking I enabled nav sidebar:
doc.body_no_toc %= "${doc.body_toc_group}"If there was a way to pass hasToc, that would better but that works as a workaround.
Yeah, that was my point. :-)
Oh, I see what you did there: you added a reference to nimdoc.cfg later so my message looks like I'm repeating yours. Outstanding move!