Skip to main content

Hosting Cesium Sandcastle with GitHub Pages

Tiffany Lu

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.

  1. Set up GitHub Pages.
    GitHub Pages supports user sites hosted at http://username.github.io, or project sites hosted at http://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 to master. If you’re creating a project site, you’ll want to create a gh-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 at http://username.github.io/repository.
  2. Remove the /Build directory from the .gitignore file in your pages repository or gh-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.
  3. Add a .nojekyll file to the root directory of your pages repository or gh-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.
  4. Build with combine to prevent a console warning in Sandcastle, using ./Tools/apache-ant-1.8.2/bin/ant build combine.
  5. Publish your site to GitHub Pages by pushing to your pages repository or gh-pages branch, and voila!