TL; Dr
Booklisp is a tool that makes managing your readme file easier and more dynamic.
Photo by Ichad Windhiagiri from Pexels
What is Booklisp?
There are 4 types of open source (OO) software. The first is where the creator(s) see a general need and then go about providing a solution for that need. The second type of OO software, is where someone has a, potentially novel, idea and they go about creating it. The third type of OO software is where someone sets out to learn something and does that learning in a space where we all can see the result. The last type of OO software is where the creator(s) have a problem that no one else has solved. So they go about solving that problem and share their solution with the world, just in case someone else has the same problem.
It is the last type of open source software I want to talk about today. Booklisp is a tool that solves a specific problem. It makes it easy to build and maintain complex documentation. It does this by allowing the author(s) to separate the document into multiple markdown pieces, and then “compiling” them into a single markdown document with a table of contents.
Why Should I Care?
Booklisp, improves upon the Readme.md file that is used to document so many open source projects. By breaking the document up into sections or chapters, you can now separate concerns in the documentation. Not only is each chapter smaller and thereby more navigable, but also you can tell what has changed by what document has changed. This is a nice feature of Booklisp. It makes it easy for those watching your releases to know what has changed with little to no effort.
It also means that if you have portions of the document that are auto generated (by All Contributors for instance) are in separate files and unlikely to be accidentally changed.
The other beauty of Booklisp is it makes it dead simple to reorganize your document. Changing chapter order is as easy as changing the order of single lines of code.
Do I use it.
Yes. Here are a few examples:
Note: Be sure to look at the raw files
Call to action
Honestly, give it a try and let its creator know. It’s awesome and I am sure he would love to hear of people using it.