-
Notifications
You must be signed in to change notification settings - Fork 4
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 [email protected] 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 may fail.
Pages has been made more robust in handling merge problems - it now falls back to a force-pull which has resolved most of the merge problems we used to experience. However if you are getting merge errors reported in your build log, let me know at [email protected] .
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 and code changes would have to be made. Contact [email protected] 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 Ruby 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 Jekyll site generation with a local web server and browser 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 there are any ruby gems (e.g. Jekyll plugins) used by your site, they should be listed only in your _config.yaml file. They must be in Pages' whitelist or they will be ignored.
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 or any of the other GitHub default Jekyll-related gems 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" # <====== COMMENT THIS LINE OUT
# 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
# If you have any plugins, put them here!
# group :jekyll_plugins do # <======= COMMENT THIS LINE OUT
# gem "jekyll-feed", "~> 0.12" # <======= COMMENT THIS LINE OUT
# end # <======= COMMENT THIS LINE OUT
...(remainder of the file)...