The AllenNLP website is for the most part a static website. There is no CMS driving any of the content. However, the site is using html abstraction (in the form of includes) to make it easier to edit and maintain. Includes are not a feature of static html, so this abstraction is being handled via Jekyll.
Since the AllenNLP website is hosted on GitHub Pages, Jekyll was the logical choice, as GitHub supports Jekyll out of the box. More about GitHub Pages and Jekyll
Introduction to Jekyll
From the Jekyll Homepage:
Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through a converter (like Markdown) and our Liquid renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server.
Since GitHub Pages has deep integration with Jekyll, they make it very easy to run Jekyll sites on their servers. You don't need to configure anything or monkey with build processes. GitHub does that all automatically. You simply push your files and GitHub does the rest.
Here's a tutorial video that outlines Jekyll basics and how the system works.
Modifying the Website
- Edit file(s) locally
- Test changes in browser at localhost
- Commit changes and push to
- Test changes in browser at http://www.allennlp.org (usually takes at least 30s to update)
After you've committed your changes, push with the following command:
$ git push
Anatomy of the AllenNLP Jekyll Site (simplified)
📂 _includes // Where html includes go 📂 _site // Generated files. Do not edit. 📂 assets 📂 css 📂 js _config.yml // Main config file for the Jekyll site. .gitignore // Ignores changes to generated _site folder CNAME // Points GitHub Pages to allennlp.org Gemfile // Configs Jekyll version Gemfile.lock // Dependencies index.html ...more html files
Install Jekyll Locally
Before pushing any changes to the website, you should test them locally in browser. In order to do that, you will need to install Jekyll on your machine.
The most important thing is making sure you have a supported version of Ruby installed.
As of 08/15/17 it requires Ruby version 2.4.1. Note that OS X Sierra (10.12) ships with Ruby version 2.0 by default, so you may need to update. See Installing/Updating Ruby on OS X on the Ruby Homepage.
Once you've verified you are up-to-date with Ruby then you can install Jekyll with a single command:
$ gem install jekyll bundler
Running Jekyll Server
Navigate to the local directory where you've checked out the
master branch and enter the command to run Jekyll.
$ cd allennlp-website $ bundle exec jekyll serve # => Now browse to http://localhost:4000
Now you should be able to see your edits reflected instantly..