Alex Ponomarev

Javascript web development notes and experiments

Gitbooks documentation for your open source project

Some time ago I started working on open-source npm module, mobx-model. I'll write more about it and wonderful mobx library a bit later. There are some interesting challenges in publishing OSS that you don't have in typical web development project. For example I've noticed that preparing a module for publishing can be quite complex. You need to set up transpiling, creating bundle, including dist files and source files and other things. This is something I'll also cover in the future cause I haven't figured out the whole process yet. Another big challenge is setting up documentation workflow and that's something I want to share in this post.

My first approach was writing several markdown files similar to README.md that you have as index page on github. I quickly noticed that this solution is not sustainable — there's no quick way to link those files. If you do link them then you will have to update links on every change manually. For example I had to change the repository name.

Next iteration was to use gitbook service. I noticed that projects like mobx and redux are using it, so why shouldn't I do the same? It proved itself to be useful — you can create a book that consists of same markdown files, but the editor does some nice things for you. It maintains table of contents, generates a website and provides a lot of extra functionality like version history (via git), custom domains, various plugins and integrations.

Finally I realised that I want my docs to live within the project repository. This approach has many benefits, for example other contributors can help you edit docs and you can have version history for documentation at the same place as the rest of the project. After some googling I found a great article on medium that explains how to have the best of both world — have markdown docs in your project repository and use gitbook command-line interface to generate static website and publish it with github pages. You can find this approach implemented for documentation of current version of mobx-model though docs itself are not finished yet.