Skip to content

FAQ

Jump to bottom
Steve Barber edited this page Mar 11, 2019 · 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 - just place an empty file named .nojekyll (note the dot!) in the root of your nist-pages branch to prevent Jekyll from processing the files. (Jekyll often will not interfere, but if you have any directory names starting with an underscore, Jekyll will not publish them.) See here for more info.

Clone this wiki locally