-
Notifications
You must be signed in to change notification settings - Fork 4
Compatibility with GitHub
At the time of its creation, GitHub Pages did not meet a number of NIST's IT security requirements - mainly that it did not require SSL and it was not hosted on a nist.gov DNS domain under a nist.gov SSL certificate.
GitHub Pages was developed by (presumably) a team of full time developers. Their code is proprietary.
NIST Pages was initially developed by one overworked NIST EL IT (ELDST) staffer in less than a week in response to an urgent and pressing need from a lab customer who was unaware that GitHub Pages was not authorized for his use and had invested a lot of development into a collaborative GitHub Pages site for an upcoming deadline. Ongoing support for NIST Pages is by the same developer in whatever spare handful of hours he can find per month. Support is not currently funded. The code in use at NIST was originally forked from GSA's 18F group's pages-server project which was designed to respond to the same need.
NIST Pages attempts to provide the same fundamental service as GitHub Pages, which is to automatically publish static web content pushed to a specific branch in a GitHub repository, processing that content with Jekyll which allows you to use templates to easily create a consistent style/theme for your site.
Since NIST Pages is only an approximation of that basic fundamental GitHub service, you may discover certain specific functionality on GitHub Pages that does not exist or does not function properly on NIST Pages.
For the most part, differences you might encounter between GitHub Pages and NIST Pages have to do with the implementation of the Jekyll site building process that extracts your site content from the GitHub repo, processes it, and publishes it on the pages.nist.gov server.
Now that we automatically update the github-pages Ruby gem, software version differences should no longer be a problem.
Over the years GitHub has added additional features and capabilities that may or may not be reflected in the NIST Pages service. One example is that NIST Pages requires use of a specifically named branch, whereas GitHub seems to offer customization of the specific branch name, and also an option to use a subdirectory instead of a separate branch. These are not possible on NIST Pages (yet). Maybe someday.
We now use automated updates of Jekyll and specific Jekyll Plugins and Themes (see below). Updates are performed nightly to install the same version of Jekyll and the authorized Jekyll Plugins to match the versions that GitHub uses. This is done by updating the Ruby gem github-pages on the server, which will pull in the same versions that GitHub uses.
Jekyll site building on pages.nist.gov is done using safe mode, which prevents arbitrary plugins from being used. We configure a list of default plugins (loaded by default unless your _config.yml file specifies otherwise) and whitelisted plugins (the default plugin list plus some additional ones that are not loaded by default) based on the contents of the github-pages rubygem. These lists are manually updated, but they don't seem to change often. See https://github.com/github/pages-gem/blob/master/lib/github-pages/plugins.rb for the source of these lists.
You can also install the github-pages gem locally and use the command github-pages versions to get a list of all the plugins, themes, and versions permitted.
All other plugins will be ignored.
As of 3/11/2019, the configured plugins are:
| Plugin | Default? |
|---|---|
| jekyll-coffeescript | X |
| jekyll-commonmark-ghpages | X |
| jekyll-feed | |
| jekyll-gist | X |
| jekyll-github-metadata | X |
| jekyll-paginate | X |
| jekyll-redirect-from | |
| jekyll-seo-tag | |
| jekyll-sitemap | |
| jekyll-avatar | |
| jemoji | |
| jekyll-mentions | |
| jekyll-relative-links | X |
| jekyll-optional-front-matter | X |
| jekyll-readme-index | X |
| jekyll-default-layout | X |
| jekyll-titles-from-headings | X |
| jekyll-include-cache | |
| jekyll-octicons | |
| jekyll-remote-theme |
To set specific plugins you want to use on your site (assuming they're on the list above), add the following to your _config.yml file:
gems: ["jekyll-sitemap", "jekyll-readme-index"]Note that you must include all needed plugins in your list, since that will override the default settings.