-
Notifications
You must be signed in to change notification settings - Fork 5
FAQ
Yes, the following things are known to cause problems requiring manual intervention with the Pages server:
- DO NOT use force-pushes (see here for more info and a way to prevent inadvertent force-pushes).
- 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.
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.
https://pages.nist.gov/REPO/build.log
Usually the root page of your repo: https://pages.nist.gov/REPO
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.
No. The nist-pages branch generally should not have Gemfile or Gemfile.lock included. Gemfiles are usually only needed for Jekyll applications - but those should almost always reside in the master branch. The only real exception is if you use bundler in combination with jekyll serve to test your site generation in a local web server before committing changes to the repo which will publish them immediately, possibly before you're ready. If that is your use case you still don't need to use bundler and Gemfiles - you can manually install the GitHub-approved gems ( gem install github-pages ) and then run jekyll directly ( jekyll serve ) without much more effort, and your pages site will be more robust.
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.
Note that there may be use cases where a Gemfile might be needed to enforce specific versioning, however those are specialized cases and having it will make your site more fragile in terms of the Pages build process. Therefore it's not recommended.
Also note that if the build process detects a Gemfile.lock without any Gemfile then it will remove the lock file before running Jekyll.
Additional info - If you have a Gemfile in the nist-pages branch (which again, 99% of cases should not have), please be absolutely certain that it does not specify a version of Jekyll that is newer than the GitHub-approved version. This happened recently and it caused a lot of difficult-to-track-down problems. You can find the list of GitHub-approved versions, the same versions NIST pages uses, here: https://pages.github.com/versions/
Yes. If your Gemfile was automatically generated by a local version of Jekyll, it may well have instructions in it that tell you how to modify it for use with GitHub Pages. Follow those instructions.
In particular, it should not specify a gem version for jekyll directly, and should instead specify the use of the github-pages gem (with no version specified).
It will generally look something like this AFTER modifications for Pages:
source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
# gem "jekyll", "~> 4.1.0" # <====== COMMENT THIS LINE OUT
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins # <======= UNCOMMENT THIS LINE
...(remainder of the file)...