Maintaining Documentation of JS Library in Lockstep With Code
I’ve long been aware of GitBook.com as a way to easily author documentation pages. What I did not know before
was that it also comes with a robust tooling for building the book locally and building as a static website.
Works great with GitHub Pages, albeit needing some specific setup to run from the
/docs folder. In itself
though it may just be a good-looking alternative to other static page generators or documentation builders.
The difference however is the abundance of plugins, and one plugin in particular useful for documenting JS
Setting up GitBook for GitHub pages
The GitBook toolchain has some setting which collide with how GitHub Pages expect you to organize your repository. It’s nothing really problematic but impossible to change so you may as well be aware of how to work with both together.
The first step is to prepare your repository to host both code and documentation. See this gitbook to set up and install the command line tool.
Next, initialize a folder for the markdown sources of your documentation pages. I called that folder
You can do it by running the command below.
You will also have to create a
book.json configuration file pointing to the root of you book
1 2 3
To test your GitBook locally you can run
gitbook serve. Note that you will want to ignore a folder called
_book which is where the site is being generated for serving locally.
Once you’ve created some pages you build static documentation pages by running
gitbook build. In the latest
version of GitBook CLI there is no setting to control the output folder and it will by default write the
output to the same
_book folder. GitHub pages however expects the static pages to be served from a
folder, which also cannot be changed. The only way to make both happy is to pass an output folder to the
build command. I added a complete command to my
1 2 3 4 5
This will take the sources from the root, as set up in
book.json and write HTML to
/docs. That should be,
just commit and push to publish your book on github.io.
Writing live snippets…
RunKit is Node prototyping
It lets anyone create actual live snippets running node with any package available on npmjs.org registry.
It is actually possible to load any particular version, similarly to how you would install a specific version
with Yarn on NPM. Additionally it also wraps the snippets in an async function so that they can use the
await keyword instead of promises and renders a nice output for JS objects or HTML. Go ahead and see what
happens when you paste the snippet below snippet on runkit.com.
1 2 3 4
…inside you GitBook…
Finally, the GitBook plugin makes it trivial to embed actual snippets within your documentation. To install
it add the plugin in you
1 2 3 4 5
Now you can add a runkit embed using a special
1 2 3 4 5 6
…and keeping them up to date with code
The ability to request any chosen version from NPM has one great implication. You can have the embedded snippets always use a version matching the state of the repository. Instead of keeping a concrete number in the runkit snippets, GitBook lets the authors create variables and inject them in their pages. Here’s my config file:
1 2 3 4 5
It defines a variable which I use in all my snippets so that they use the most recent version of my library:
1 2 3 4 5
At this point there are simple steps to follow in order to always have the documentation using the right version:
- Change my code as usual
- Publish next version to NPM
- Update documentation
- Bump the GitBook
- Build GitBook
- Commit, tag and push repository
This way the online documentation always point to the most recent version but anyone checking out any tag will be able to run the documentation as it existed at that point in time. And the code examples will use the matching version from NPM!
Bonus: documentating multiple versions of the library
With a simple modification of these steps one could also keep multiple versions of the documentation, targeting multiple versions of the library.
- Build the book to a
- Whenever you’re ready to tag you repository, make a copy of that folder to one named after the
version. For example
This way you will keep all past versions documented alongside the latest on
See it in action
Go ahead and check Alcaeus’ documentation pages at https://alcaeus.hydra.how to see live examples published using the RunKit plugin.