Main menu

Post navigation

Project Documentation with Hexo Static Site Generator

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:

nvm install 4

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:

git --version

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.

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:

git clone https://github.com/USERNAME/REPOSITORY.git

Replace USERNAME with your username and REPOSITORY with the name you gave to your repo. In my case, the command would be:

git clone https://github.com/sitepoint-editors/hexo-documentation.git

Now let’s cd into it and create a folder called docs:

cd hexo-documentation
mkdir docs

The docs folder is where our documentation site will be, and it’s where we’ll initialize Hexo by running:

hexo init docs

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: