Troubleshooting

What self-help tools are available to me?

In general there are two ways errors will be reported to you. They both contain the same information, a log of the output of the build process.

1. Via email. When a build error is detected, a copy of the build log will be emailed to the email address(es) of the person who submitted the commit and the person who pushed the commit to the server. This may fail if the supplied email addresses are invalid or non-functional. Note that it may go to your personal email address and/or your NIST email address.
2. If the site has been successfully published at any time in the past, you should be able to view the most recent build report by visiting (for example for a repository named REPO) https://pages.nist.gov/REPO/build.log

My site didn't publish after I completed configuration, what now?

The initial creation of a new site has been somewhat fragile and it would be best to ask us to help you debug it. Email pages@nist.gov for assistance.

It didn't work. Can I test against GitHub Pages?

By policy: no.

Any required Jekyll _config.yml settings?

To get the paths to work right on pages.nist.gov I recommend at a minimum:

baseurl: "/REPO"

That's not strictly needed if you have a single page site for example.

How can I develop my site without publishing every little update?

You can run jekyll locally on your workstation while you develop your site to avoid having to push hundreds of test changes up to github. You will need the correct version of ruby on your workstation (see https://pages.github.com/versions).

Once that is installed you can install Jekyll and all the Pages-related plugins and modules by installing the github-pages gem.

gem install github-pages

You should add _site to your .gitignore file. (This is where a local Jekyll instance will place the generated HTML, but it's not necessary to place generated HTML under version control since you can just regenerate it.)

Running jekyll serve in the root of your local repository will start a local web server process on your workstation, usually on port 4000. It should generate the site into _site and then continue to watch for files to change. If you change any of the source files it should regenerate the site.

Then just open a browser window and go to https://localhost:4000/REPO/ (note the trailing slash!).

Why does my site keep disappearing from the server?

If you publish your site to pages and all seems well, but then you sometimes get 404 "Not Found" errors, the problem is most likely that the source GitHub repo has not been made public. There is a nightly cleanup job that removes stale repos and one of the criteria is that the site (a) has a nist-pages branch and (b) is public. If either of these is not true, the repo and the generated site will be removed from Pages. If your webhook is still configured, the site will still publish upon pushing to GitHub, but the cleanup script will find it and remove it later. I will try to figure out a way to make this behavior more obvious (maybe an email alert to the repo owner when a site is purged, and testing for public status before the initial publication?) but for now just be aware that if your site seems to disappear randomly, this is probably why.