When starting an open source project, one of the most important things is to create project documentation. Documentation is essential if we want our project to be used by others, and it can be done in many ways:
GitHub Wiki - GitHub lets us make a wiki associated with each project. It is composed of pages written with markdown and is definitely a tool to take into consideration to build documentation. However, it does have a few limitations: contributions to a wiki don't appear in the project contributions; is limited to a strict structure and layout; you must host assets in other locations.
README - we can create a README.md, which will show on the GitHub project page. It might be a good solution if the documentation will be very short, otherwise it gets a big one page full of information. Usually this serves to introduce the project and not to show documentation.
Self Hosted - we can create a custom site for our documentation. This gives us total freedom to create what we want, but it prevents possible contributions to our documentation. It also comes with the price of hosting.
GitHub Pages - GitHub also provides a way of hosting a static site for each project. By creating a branch called gh-pages in your project's repo, GitHub will publish its contents as a website. This is great to place a documentation site, although, maintaining documentation in a separate branch is not optimal: documentation files get hard to find for contributors and contributions won't show up in the master branch.
Fortunately, there's a way of combining the best parts of the options above.
Introducing Hexo
Hexo is a static site generator built with Node.js. It is mostly used as a blog framework, but it has a deploy integration for GitHub which makes it a great fit to build a documentation site for a GitHub project.
With Hexo, we can create markdown files and HTML layouts which will be converted to static HTML files when deployed. Hexo provides a deploy configuration which builds our static files into a GitHub branch. This means we can maintain our documentation as markdown in our project's master branch and deploy it, with one command, to gh-pages.
Installing Hexo
Hexo is built with Node.js, so to install and use it we'll need Node.js installed in our system. We'll also need Git which will be used by Hexo to deploy our documentation site to gh-pages.
Installing Node.js
To install Node I recommend using a version manager, such as nvm. There are other version managers out there that you can use, but they all make life easier when it comes to installing and switching between Node.js versions.
Using nvm, let's run the following:
This will install the most recent release of Node.js 4.x, which also comes with npm ready to use.
Installing Git
We'll also need Git installed in our system. If you're not sure you already have it, run the following:
If the result is a Git version you can skip this section. If instead you see an error, you'll have to install it first.
Windows
On a windows system we can run an installer provided by Git.
OS X
On OS X, we can install it in one of three different ways:
Using the installer.
Using Homebrew by running brew install git.
Using MacPorts by running sudo port install git +doc +bash_completion +gitweb.
Usually, I prefer using Homebrew to install this type of software, but if you're more familiar with MacPorts or just want to use the installer, there's nothing wrong with that.
Linux - Ubuntu or Debian
On an Ubuntu or Debian-based system we can install Git with apt:
Linux - Fedora, Red Hat or CentOS
On a Fedora, Red Hat or CentOS system we can install Git with yum:
Installing Hexo CLI
After installing Node.js and Git we can now finally install Hexo by running:
To make sure everything is set up, type the following:
If you see a list of versions, good news: you have everything ready to use Hexo!
Setting Up
Now that we have Hexo installed, we can now start to create our documentation on our GitHub master branch. To follow this article, you can either:
Create the documentation for one of your existing GitHub projects
Create a new repo here
For simplicity, I'll assume you're creating a new project called hexo-documentation, but you can follow the article with an existing one.
Let's clone the GitHub repo locally by running:
Replace USERNAME with your username and REPOSITORY with the name you gave to your repo. In my case, the command would be:
Now let's cd into it and create a folder called docs:
The docs folder is where our documentation site will be, and it's where we'll initialize Hexo by running:
What the command above does is add a bunch of Hexo's configuration and dependency settings. But we still need to install those dependencies, which are defined in a package.json file inside the docs folder. To do so, let's run the following:
Continue reading %Project Documentation with Hexo Static Site Generator%