Welcome to the SpaacedOut Jekyll Theme

Here's a new, responsive GitHub Pages and Jekyll theme called SpaacedOut. You can see the full details of this theme at jasongaylord/SpaacedOut. This theme is a mashup of the 2019 version of JasonGaylord.com, the Haacked theme, and the plainwhite theme.

This theme has several features enabled by default:

  1. Post Excerpts on the Home Page

  2. Google Analytics tracking

  3. Post Archival by Year

  4. Social Media Icons in the Site Header

  5. Disqus comment support

  6. Dynamic menu support

  7. Automatic Line Numbering and Language Indicator for Syntax Highlighting

  8. Git link for editing

These features are explained in greater detail in the custom installation section below.

Installation

This theme is typically used as a remote theme on GitHub pages and through the Jekyll remote theme plugin explained on my blog.

To use the theme, there are two different methods:

  1. Abbreviated Installation - A quick installation to begin using SpaacedOut right away

  2. Custom Installation - A more in depth overview to allow customization of the SpaacedOut theme

Abbreviated Installation

Please note that if you have modified your _config.yml already, you should probably resort to the Custom Installation instructions below.

To get started, you should copy all {settings from the SpaacedOut _config.yml} and past the values into your _config.yml file replacing everything. Next, review the settings and modify the values to reflect your site (i.e. Change 'My Blog' to the title you'd like on your site).

If you are looking for futher customization, please continue. Otherwise, you should be ok to check in your changes and view the site in GitHub Pages.

If everything came out ok, it should resemble this:

In addition, there's full mobile support with a flyout menu:

Custom Installation

Below you'll find a basic overview to customize the theme. In addition, each area of the configuration is explained via comments in the {_config.yml} Additional details to assist in customizing the theme can be found in the Dissecting the Theme section below.

Home Layout

home.html is the default page for the site and is the initial page that loads when your site loads. The current home layout includes a placeholder for text followed by a paginated list of posts. The placeholder will allow you to add content to index.html or index.md (located at the root of your site) which will be placed above the paginated list. This is a great way to introduce the visitors to your site.

In addition, if you include <!--more--> in your post, only the content above the comment will be shown as an excerpt on your homepage and within the post archives.

Content Extras

Rather than overriding each of the includes or layouts simply to add content, I've added a mechanism to add content to the common areas of the site. Since GitHub Pages currently supports Jekyl 3.8 and not 4.0, we cannot use dynamic includes. The following are configuration elements that, when setting the value to true, will render their respective files in your sites local _includes folder. These files can be defined under the content node in the _config.yml file:

Override Layout, Includes, or Style

Any of the layouts or includes can be overwritten. Simply copy over the file or directory to your site and modify as you see fit.

If you are looking for your own color scheme, fonts, or sizes, I'd recommend the following steps:

  1. Create your own SASS file in the assets directory called style.scss.

  2. Copy the variables found in sass\variables\variables.scss in the SpaacedOut theme into your new style.scss file. You only need to include the variables that you are replacing.

  3. Below the variables contents you just copied, add a new line to import the SpaacedOut.scss file like:

@import "SpaacedOut";

Dissecting the Theme

Layouts

The files mentioned below can be found in the _layouts directory. If you are unfamiliar with layouts, these are similar to a template or master page in other languages.

Includes

The files mentioned below can be found in the _includes directory. Includes are partial content that can be injected and loaded in either a layout or another include.

Styles

There are two primary style sheets that are referenced in the _includes\head.html file. You'll notice that both reference a .css extension as opposed to a .scss extension. This is because Jekyll compiles the SASS to CSS:

  1. assets\style.scss - This references the _sass\SpaacedOut.scss file which in turn includes variables\variables.scss and core\core.scss, both found in the _sass directory.

  2. assets\syntax-highlight.scss - This applies syntax highlighting to the Rouge highlight plugin for Jekyll. This was modified slightly from the post found at textuploader.com/1odmf.

Included Pages

Inside of the assets folder, you'll find a pages directory. Currently, only the archives.md file exists inside of this directory. This file displays the archive menu option in the theme and lists the posts in descending order by year.

Scripts

Inside of the assets folder, you'll find a js\utils.js file. You'll notice that throughout the site, I'm not using a JavaScript framework, such as jQuery, or a CSS framework, like BootStrap. The goal is to keep this theme very lightweight. So, the utils.js file contains a namespaced list of functions.

Plugins

The following plugins are installed in the SpaceOut theme:

Contributing

Bug reports and pull requests are welcome on GitHub at github.com/jasongaylord/SpaacedOut.

Development

I've blogged about getting started with themes and Jekyll. You can read more about it at www.jasongaylord.com/blog/creating-a-jekyll-theme-from-windows

License

The theme is available as open source under the terms of the MIT License.

Change Log

The changes made since version 1.x are documented below.

Version 1.1.x - July 9, 2020

Version 1.0.x - May 15, 2020