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, make sure wget
is installed and run make linkchecker
, which will produce a report of broken links. However, no URL of parent webpages that contain broken links will be reported, but one can use grep
command to find those parent webpages.
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.
A one-time setup is required to initialize the website/public
submodule:
$ rm -rf website/public $ git submodule update --init $ cd website/public $ git checkout gh-pages $ git remote rename origin upstream
With the submodule in place, 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 'upstream/master'. $ cd website/public $ git status On branch gh-pages Your branch is up-to-date with 'upstream/gh-pages'.
To publish the site docs:
website/public
directory, commit everything to the gh-pages
branch and push to the upstream
repo. You can also push to the gh-pages
branch of your own fork and verify the site at http://[username].github.io/heron
.