Member-only story
Easy way to create your Documentation site with Docsify and GitHub Pages
Documentation is an essential part of making any open source project useful to users. But it’s not always developers’ top priority, as they may be more focused on making their application better than on helping people use it. This is why making it easier to publish documentation is so valuable to developers. In this tutorial, I’ll show you one option for doing so: combining the Docsify documentation generator with GitHub Pages.
If you prefer to learn by video, you can access the YouTube version of this how-to:
By default, GitHub Pages prompts users to use Jekyll, a static site generator that supports HTML, CSS, and other web technologies. Jekyll generates a static website from documentation files encoded in Markdown format, which GitHub automatically recognizes due to their .md or .markdown extension. While this setup is nice, I wanted to try something else.
Fortunately, GitHub Pages’ HTML file support means you can use other site-generation tools, including Docsify, to create a website on the platform. Docsify is an MIT-Licensed open source project with features that make it easy to create an attractive advanced documentation site on GitHub Pages.
Get started with Docsify
There are two ways to install Docsify:
- Docsify’s command-line interface (CLI) through NPM
- Manually by writing your own
index.html
Docsify recommends the NPM approach, but I will use the second option. If you want to use NPM, follow the instructions in the quick-start guide.
Download
Download the sample content from GitHub
I’ve published this example’s source code on the project’s GitHub page. You can download the files individually or clone the repo with:
git clone https://github.com/bryantson/OpensourceDotComDemos
