Skip to content

FAQ

Jump to bottom
Steve Barber edited this page Jan 14, 2020 · 19 revisions

Anything I should not do with git?

Yes, the following things are known to cause problems requiring manual intervention with the Pages server:

  1. DO NOT use force-pushes (see here for more info and a way to prevent inadvertent force-pushes).
  2. DO NOT delete your repo and recreate one with the same name. (If you must start over, either ask for assistance from pages@nist.gov or delete it and then wait overnight until the old site is removed before creating the new one.)

Most problems occur because people aren't aware that the Pages server uses a clone of your repository which it attempts to update via git pull. If the pull fails, e.g. because manual merging is required, the build will fail.

Can I publish content from a different organization or my personal account?

Generally no, although there is precedent for publishing NIST-related content from a non-USNISTGOV GitHub organization that is highly related to NIST business and is appropriate to publish under the nist.gov domain, but a special exception would have to be made. Contact pages@nist.gov if you believe you have such a case.

What was the URL for the build report?

https://pages.nist.gov/REPO/build.log

What URL should I publish?

Usually the root page of your repo: https://pages.nist.gov/REPO

Is there a template for starting a new Pages site?

The most complete (but older) Jekyll template is still https://github.com/usnistgov/Pages-Template . You could start by downloading a zip of that repository into a new empty git repo and using that as a starting point.

For those who are comfortable with GitHub and Jekyll already and don't want the overhead of that project, we're starting to move toward using the instructions at https://pages.nist.gov/nist-header-footer (https://github.com/usnistgov/nist-header-footer). We may eventually change the Pages-Template template to use this same method of linking in the required NIST headers/footers/exit scripts, rather than making separate copies for every repo.

There are big advantages of using the latter method:

  • Trivial to set up - paste 3 lines into your template(s) HEAD section and it just works
  • No files to copy into your repo
  • That means you don't need to do anything when they're updated

Can I simply publish a pre-generated static site, e.g. via Sphinx or other software, without messing with Jekyll?

Yes. Without specific configuration Jekyll generally just copies files it doesn't recognize, but it does handle certain file names and patterns differently, for example if you have any directory names starting with an underscore (like _static), Jekyll will not publish them.

To prevent any interference from Jekyll processing, just place an empty file named .nojekyll (note the dot!) in the root of your nist-pages branch. This will simply copy the source tree verbatim without any Jekyll processing at all. See also this entry about Sphinx for more info.

Do I need a Gemfile or Gemfile.lock in my repo?

No. The nist-pages branch should not have Gemfile or Gemfile.lock included. If you do include them or have included them in the past then you may run into versioning problems with the ruby gems that Jekyll tries to load. If your repo already has one or both, please remove them from your repo. If you only had a Gemfile in the repo then the server will have generated its own copy of Gemfile.lock which will have to be manually removed. Please contact pages@nist.gov if you only have/remove a Gemfile so the lock file can be removed from the server.

If there are any ruby gems (e.g. Jekyll plugins) used by your site, they should be listed only in your _config.yaml file. Jekyll will take care of the rest.

Clone this wiki locally