Heron Documentation

Heron's documentation was primarily built using the following components:

• Hugo --- Static site generator
• GulpJS --- Build tool for static assets
• Twitter Bootstrap --- CSS and JavaScript

Documentation Setup

Running the Heron documentation locally requires that you have the following installed:

• Make
• Node.js
• npm

OS X Setup

To install Node.js and npm on Mac OS X, make sure that you have Homebrew installed and run:

$ brew install nvm
$ nvm install node
$ curl -L https://www.npmjs.com/install.sh | sh

Once this has completed:

$ cd website
$ make setup

This will install Hugo, Gulp, and all of the necessary Gulp plugins and build the static assets for the site.

Other Operating Systems Setup

Although the documentation is currently set up to be built and run on OS X, it's also possible to do so on other systems. In addition to Node.js and npm you will also need to install Hugo. Once those are installed:

1. Navigate to the website folder
2. Run npm install
3. Run npm run build (this will build all of the necessary static assets, i.e. CSS, Javascript, etc.)

Building the Docs Locally

To build the docs locally:

$ make site

This will generate a full build of the docs in the public folder, checking all links. If broken links are found, see linkchecker-errors.csv.

Running the Site Locally

To serve the site locally:

$ make serve

This will run the docs locally on localhost:1313. Navigate to localhost:1313/heron to see the served docs. Or open the browser from the command line:

$ open http://localhost:1313/heron

Publishing the Site

The content on the twitter.github.io/heron website is what is committed on the gh-pages branch of the heron repo. To simplify publishing docs generated from master onto the gh-pages branch, the output directory of the site build process (i.e., website/public) is a submodule that points to the gh-pages branch of the heron repo. As a result you will notice that when you cd into gh-pages and run git status or git remote -v, it appears as another heron repo based of the gh-pages branch.

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
$ cd website/public
$ git status
On branch gh-pages
Your branch is up-to-date with 'origin/gh-pages'.

To publish the site docs:

1. Make the site as described in the above section. Verify all links are valid.
2. Change to the website/public directory, commit and push to the gh-pages branch.