Introduction

I host my programming course on GitBook and it’s great (the GitBook system I mean, not my course…albeit it’s not that bad either 🙂 ).

However, recently I started looking for alternatives in case GitBook stops being free.

I’ve been a big fan of GitBook from its early days. You simply write your stuff in markdown, push your stuff to your repository and behold “a full-blown online course”. You want an epub or PDF version of your document? No problem, all the GitBook tools are available on GitHub. But how long will it last?

Docsify.js became my fallback because it allows a rather painless migration.

Why GitBook might need an alternative soon?

Recently gitbook.com launched a new version and went rather more commercial. They abandoned markdown for their own proprietary JSON-format and git-like repository. You can still use the classic markdown+GitHub combination, but you won’t be able to use all the latest neat stuff (tabs, etc.). In fact, the developers have bluntly stated they won’t be keeping the open-source tools up-to-date.

Why docsify.js is my backup plan?

There’s still a free plan at GitBook, so at the moment there’s no reason to panic, but one should be prepared. My main goal was to find a system that would allow me to ‘convert’ my existing GitBook-course to another system with the least amount of hassle possible. Docsify.js became my fallback technology for now. It requires minimal changes to my markdown-course AND allows free hosting on GitHub pages, resulting in a perfect alternative to GitBook.

How to migrate to docsify.js?

• Install docsify

  npm  i docsify-cli -g

• (Make a copy of your existing repo)
• Initialize docsify on your repo folder: docsify init [yourrepo]   (notice that this will overwrite your existing Readme.md, so make sure to replace it afterwards)
• Rename summary.md to _sidebar.md (yes, it’s that simple!)
• Add loadSidebar: true to window.$docsify in index.html
• That’s all there is to it! Now run: docsify serve
• And push it to Github Pages as explained here

If your images don’t work, make sure your references aren’t correct. Check out the end of this article for tips on this.

Images/references

All my images are stored in a separate asset folder. GitBook doesn’t mind URLs such as “/assets/0_intro/vslogo.png”, it will automatically append the root folder in front and find the needed resource.

For docsify it’s important you add “..” in front otherwise docsify won’t find the asset folder: “../assets/0_intro/vslogo.png”