Heron's documentation was primarily built using the following components:
Running the Heron documentation locally requires that you have the following installed:
To install Node.js and npm on Mac OS X, make sure that you have Homebrew installed and run:
$ brew update && brew install nvm && source $(brew --prefix nvm)/nvm.sh $ nvm install node $ curl -L https://www.npmjs.com/install.sh | sh
Once this has completed:
$ cd website $ make setup $ make build-static-assets
This will install Hugo, Gulp, and all of the necessary Gulp plugins and build the static assets for the site.
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:
website
foldernpm install
make build-static-assets
(this will build all of the necessary static assets, i.e. CSS, Javascript, etc.)To build the docs locally:
$ make site
This will generate a full build of the docs in the public
folder, a full build of the static assets in the static
folder, and check all links. If broken links are found, see linkchecker-errors.csv
(you can safely leave this file in your directory, as it is ignored by Git).
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
If you‘d like to work on the site’s static assets (Sass/CSS, JavaScript, etc.), you can run make develop-static-assets
. This will build all of the static assets in the assets
folder, store the build artifacts in the static
folder, and then watch the assets
folder for changes, rebuilding when changes are made.
To verify that the links in the docs are all valid, run make linkchecker
, which will produce a report of broken links. If linkchecker
fails to install or run properly, you can install it manually. Note that due to this issue linkchecker
versions 9.2 and 9.3 require Python requests
>= 2.2.0 and < 2.10.0.
If you run make setup
you should have all of these tools available. Be warned, though, that make setup
will uninstall whichever version of requests
you currently have installed and replace it with version 2.9.0.
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 website/public
and run git status
or git remote -v
, it appears as another heron repo based off 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:
website/public
directory, commit, and push to the gh-pages
branch.