An intro website for The Policy Lab at Brown University, May 2019. Static HTML generated from Jekyll with SASS, Bootstrap 4.3, and Autoprefixer.

Grey Matter is a boilerplate for stand-alone Jekyll projects. Inspired by Distillery (and now heavily updated/modified), built and served with Jekyll, leveraging Oomph Scaffold custom code and Bootstrap 4.

To get up and running:

Navigate to the project folder in your Terminal, then install Bundler if you do not already have it installed:

{% highlight shell %} // Check to see if Bundler is installed: $ which bundler

// If no response, install it: $ gem install bundler

// Once installed (or if previously installed), run inside this project: $ bundle install {% endhighlight %}

The project dependencies should now be installed.

+Note: you may need to run the installers using the $ sudo command depending on the permissions of your computer.

From the project root, run:

{% highlight shell %} $ jekyll serve {% endhighlight %}

The server is available in your browser at http://localhost:4060/policy-lab/.

If the compiled file URLs need to have a different root path, change the baseurl value in _config and restart the server. The web url will change as well, i.e. http://localhost:4060/[path]. When you upload the sites content to a server, all URLs will be prefixed with /[path].

{% highlight JavaScript %} config.yml // project set up and variables for base URL path _includes // HTML partials -- footer.html -- head.html -- header.html -- navigation.html ---- etc... _layouts // HTML templates -- default.html // Base tempalte _plugins // RB files for Jekyll plugins _sass // The gold _site // Rendered static HTML (not under version control) assets // Static assets -- css ---- main.scss // Jekyll pipeline converts this to CSS on render -- img -- js feed.xml // Sample file type XML Gemfile // Project dependency manager Gemfile.lock index.html // Site content front page etc... {% endhighlight %}

Any folder prefixed with an underscore is used as a build folder only, it is not compiled and rendered. An assets folder (unprefixed) will be included in the site build. Additional files that should be excluded from the build should be added to _config.yml.

Use _includes for repetitive elements like headers, footer, nav, etc…

Use _layouts to control larger templates. Jekyll ships with an example page and a post. Variables use a {% raw %}{% double brace %}{% endraw %} syntax, and refer to simple text declarations at the top of page files.

default.html is the base template and includes calls for a header and footer.

Page files live at the site root. All rendered HTML and assets go into the _site folder by default, from which they are served in your browser. Pages can also be nested in folders but this structure is not required for the site render. The Liquid permalink value will determine where a rendered page lives in the URL structure.

More in depth Jekyll instructions here from JekyllRB.

Markdown is supported and may be used inside files with a .md extension. A markdown syntax usage guide. Daring Fireball has a really great online converter if you need troubleshooting help.

Keep Ruby Gems and the Gemfile up to date.

bundle update jekyll

Let this command run. All dependencies for the latest stable Jekyll release will be updated and the Gemfile.lock will be updated as well. Update any very old dependency versions in the Gemfile at your discretion.

Commit the Gemfile.lock to version control if updates are made.