In creating a staging site for our work on adding CZML examples to Sandcastle, Adam and I have come across some best practices for hosting Sandcastle using GitHub Pages. Hopefully, this information can prove useful to others in the Cesium community.
-
Set up GitHub Pages.
GitHub Pages supports user sites hosted at
http://username.github.io
, or project sites hosted athttp://username.github.io/repository
, where username is your GitHub username and repository is the name of your pages repository. If you’re creating a user site, you’ll be pushing directly tomaster
. If you’re creating a project site, you’ll want to create agh-pages
branch in your project site repository. For more information on setting up pages, read through the GitHub Pages site.If you want to set up pages for an existing repository, simply create a
gh-pages
branch in your repository. Your project site will be hosted athttp://username.github.io/repository
. -
Remove the
/Build
directory from the.gitignore
file in your pages repository orgh-pages
branch.The
/Build
directory is not part of the stock Cesium repository. However in this case we want to include it, as it is where users will be running Sandcastle from.This change should be made only in your
gh-pages
branch or GitHub Pages repository. -
Add a
.nojekyll
file to the root directory of your pages repository orgh-pages
branch.GitHub Pages automatically processes your site using Jekyll, a static site generator. Since Sandcastle uses files that start with underscores and Jekyll does not copy such files to the final site, you can bypass Jekyll processing by creating a file named
.nojekyll
in the root of your pages repository and pushing it to GitHub.As with Step 2, this should be done only in your
gh-pages
branch or GitHub Pages repository. -
Build with
combine
to prevent a console warning in Sandcastle, using./Tools/apache-ant-1.8.2/bin/ant build combine
. -
Publish your site to GitHub Pages by pushing to your pages repository or
gh-pages
branch, and voila!