oomph-grey-matter

layout: text title: Read Me nav-title: Read Me permalink: readme/

Grey Matter

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

Getting started

To get up and running:

Install dependencies

Navigate to the project folder in your Terminal, then:

{% highlight shell %} $ gem install bundler $ bundle install {% endhighlight %}

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

Run the Local server and SASS compiler

From the project root, run:

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

The server is available at http://localhost:4040/grey-matter/ or http://0.0.0.0:4040/grey-matter/.

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:4040/project. When you upload the sites content to a server, all URLs will be prefixed with /project.

Project Structure

{% highlight JavaScript %} config.yml // project set up and variables for base URL path _includes // HTML partials -- footer.html -- head.html -- header.html -- navigation.html -- paragraphs // specific partials for paragraph components ---- body.html ---- etc... _layouts // HTML templates -- default.html // Base tempalte -- page.html // Base content template, inherits default -- text.html // Base text template (constrained container), inherits default _plugins // RB files for Jekyll plugins _sass // The Gold _site // Rendered static HTML (not under version control) assets // Static assets -- css ---- greymatter.sc// Jekyll pipeline converts this to CSS on render -- img -- js feed.xml // Sample file type XML Gemfile // Project dependency manager Gemfile.lock [any].html // File rendered as HTML following the directives defined // at the top of the file in "Liquid" syntax [any].md // File rendered from Markdown into HTML etc... {% endhighlight %}

Usage

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 like you would use partials in PHP 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.html is a partial, which renders where the {% raw %}{{ content }}{% endraw %} call is made. text.html is also a partial, with a max-width container around the content.

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

A markdown syntax usage guide. Daring Fireball has a really cool online converter if you need troubleshooting help.

Updates

Keep Ruby Gems and the Gemfile up to date. But update dependencies carefully. Update all might meant that you get a newer dependency than another can handle.

# A conservative update. Nothing may change. Pay attention to the output, which should include versions of all dependencies installed. 
bundle install

# Update ALL gems. Might not be a good thing to do. 
bundle update

# Update just a spoecific gem to the latest available. Also might not be the best thing to do.
bundle update [gemfile]

# Update a specific gem to a specific version. Will update other dependencies if required. The most conservative approach. 
bundle update [gemfile] [version]

# More than one gem name can be passed through the update command. This will only update the two named gem files:
bundle update rake rack

More info and commands at bundler.io