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 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.
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
npm run build
(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, checking all links. If broken links are found, see linkchecker-errors.csv
.
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
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 https://github.com/wummel/linkchecker/pull/657, linkchecker
versions 9.2 and 9.3 require the python requests
>= 2.2.0 and < 2.10.0.
$ pip uninstall requests $ pip install requests==2.9.0 $ pip install linkchecker
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:
website/public
directory, commit and push to the gh-pages
branch.