Roberto Alsina: Coding in anger: not-gitbook

I have, intermitently, for the past few months, been writing a book. You can see it here and I am fairly happy with how it's going.

I am not so happy with the tooling.

When I started writing it, I didn't want to write a tool, I just wanted to write a book. So, I looked for "things to make a book out of markdown" and found a few, including mdBook and gitbook and tried them both, then decided to go with gitbook because it seemed more developed.

But, you know how this works. Things started drifting.

One initial obstacle was that I wanted the code in the book to come from the actual working code, not be a copy. I also wanted to "execute" the chapters and make the output of the chapter's code part of the chapter itelf.

I found a nice tool for this called pyLiterate which... I ended up extending to allow for things such as "include this piece of code from that file but do not execute it" and whatever, and integrating it into gitbook involved ... a lot of Makefiles.

And then wen the output appeared in gitBook ... I really didn't like how syntax highlighting worked. I wanted prettier and specifically to be able to highlight some lines, and to have line numbers matching the file contents and not starting from 1 ... and I ended up writing a Gitbook Extension

And I added support for graphviz in pyLiterate because I wanted SVG diagrams as part of the code and not as separate things.

And I wrote and I wrote.

And then life happened and I stopped writing. And whenever I wanted to start writing again in a new setup something broke.

• Maybe the gitbook version installed or its dependencies had a security issue and needed updating.
• Maybe the updated gitbook broke my plugin
• Maybe things just were "off" and I had to track it down*

And a couple of days ago, I just got angry. And what the hell this is just a lame static file generator and I know those suckers.

So, I decided to see how much work would it be to reimplement, somewhat dumbly, gitbook.

Well, really, it's about a day's work (for a low quality version)

• Supports all I want
• Supports plugins
• Supports arbitrary markdown preprocessing
• Supports arbitrary markdown renderer hacking
• Uses mistune for markdown, which kicks ass
• Uses jinja2 for templates and they are 10x simpler than in gitbook AND THE OUTPUT LOOK THE SAME. I mean, there is one template

I logged the work, which was at a very relaxed pace over a couple of days here and published not-gitbook in gitlab

I could migrate my book to the new toolchain in a day more work, mostly involving implementing things gitbook doesn't do and I am hacking via Makefiles.

It's surely not ready for any real usage but feel free to poke around and contact me if you want to use it.

from Planet Python
via read more