Steve for Jekyll

Steve is a charming and fun blog theme for Jekyll, the static site generator. It's developed by @arthrfrts to be used on the Esporo websites — but feel free to use it in any project you may find it fitting.

See it in action on the demo site.

Installation

Add this line to your Jekyll site's Gemfile:

gem "steve-for-jekyll"

And add this line to your Jekyll site's _config.yml:

theme: steve-for-jekyll

And then execute:

$ bundle

Or install it yourself as:

$ gem install steve

Usage

Steve is made to be used with zero-configuration needed. Even so, you can customize it further with theme settings, style variables, content includes and plugin-specific configurations. We will guide you through each one of those.

Theme settings

Steve's settings are defined in your site's _config.yml:

steve:
  intensedebate_account: # get one at <https://intensedebate.com/install>
  archives: # Prefixes used with archive titles
    date: Posts from
    tag: More about…
    category: Posts filed in
  date_formats: # Uses <http://strftime.net>
    post: "%b %e, %Y" # The date format used in the post layout.
    archives: # The date formats for the archive layout.
      day: "%b %e, %Y"
      month: "%b, %Y"
      year: "%Y"
  page_404: |+
    The page you're looking for could not be found.

    Maybe the search can help.
  pagination: # Strings used in the blog- and post-pagination.
    next_page: "&laquo; Next"
    prev_page: "Previous &raquo;"
    prev_post: "Previous:"
    next_post: "Next:"
  post: # Strings used in the post layout.
    byline: "By"
    tags: More about…
  search: # Strings used in the search form.
    label: Search this blog
    placeholder: What you're looking for?
    submit: Go!

The above are the default values that Steve will use. Feel free to change the ones you want. This is useful if you want to localize the theme strings or change the date formats used by the theme.

Style variables

You can change Steve's appearance with a different color scheme or typography setting custom variables. Follow these instructions:

Create a screen.scss file in assets/css.
Add the following content:

   ---
   ---

   @import "{{ site.theme }}";

Before the @import declaration, you can set the following custom SCSS variables:

/*
  Color Scheme
*/

$color__background-content: #fff; // posts, pages and sidebar background color.
$color__background-body: #e4f0f6; // body background color:
$color__text: #000112; // body text color

$color__link: #4e9dd8; // color for links and accents
$color__link-hover: #2361a7; // alternate color for active or focused links and accents

$color__details: #939496; // color for details such as borders and shadows
$color__details-lighter: #f0f1f4; // lighter alternative for details
$color__details-darker: #6d6e70; // darker alternative for details

/*
  Typography
*/

$font__body: sans-serif; // used for the main, body typography
$font__headings: sans-serif; // used for headings and feature elements
$font__code: monospace; // used for pre-formatted text and code.

/*
  Layout
*/
$layout__container-width: 1180px; // the width of the main content (content + sidebar)
$layout__gutter: 2rem; // the spacing unit between elements.

You can change the values to any variable you want. Steve will replace the default values set by the theme with the ones you choose. Be sure that the variable definitions are above your @import "{{ site.theme }}" declaration.

Content includes

Steve supports two editable areas and three different menus.

Editable areas

You can add any content you want in your site's sidebar or footer.

Create a custom-widgets.html file in _includes/blog/ to add custom content to your site's sidebar.
Create a custom-text.html file in _includes/footer to add custom content to your site's footer.

Menus

Steve has three menu positions controlled using Jekyll data files:

_data/menu.yml — The main menu, above the website content.
_data/social.yml — The social menu, in the website sidebar.
_data/links.yml — And a third menu at the bottom of your website's footer.

Create the respective data file for the menu you want to use. Menus are a YAML List with the following structure:

- title: "About this site" # The item title
  url: "/about/" # The item URL or path
  external: true # Optional, if the link points to an external resource.
  color: "#336699" # Only on `_data/menu.yml`, the background color of this menu item.
  icon: "<svg ...>" # Only on `_data/social.yml`, the SVG icon markup for this item -- get one in <https://simpleicons.org>

Plugin-specific settings

Steve uses the following Jekyll plugins to create sitemaps, RSS feeds, archives and much more.

jekyll-feed — generates the RSS feed.
jekyll-seo-map — generates site's OpenGraph and SEO meta tags.
jekyll-sitemap — generates the XML sitemap.
jekyll-paginate — paginates the home post list.
jekyll-archives — generates the archives by date, tag and category.
jekyll-loading-lazy — adds loading="lazy" to all images and frames on your pages and posts.

While Steve sets initial configurations for these plugins, you may want to change them in your _config.yml. Please refer to these plugins documentations for further reading about how to change their config options.

Comments

Steve supports Staticman-powered comments, and provides initial settings from our own staticman.yml config file. You can create your own settings at any time, but keep in mind that Steve looks for the following fields when submitting comments:

name
email
website
message

Follow these instructions to set up your Staticman instance.

You can also customize your comments' section and submit form adding the site.comments object in your _config.yml:

comments:
  title: Comments
  form_title: New Comment
  date_format: "%b %e, %Y @ %l:%M %P"
  staticman_endpoint: # Get yours on <https://staticman.net>
  notice: |+ # Accepts Markdown
    Please be nice in the comments.

    Comments are moderated, so it can take a while for your's to show up.

    Also, you can use [Markdown](https://daringfireball.net/projects/markdown).
  fields:
    name:
      label: Name
      placeholder: "John Appleseed"
    email:
      label: Email address
      placeholder: "[email protected]"
    website:
      label: Website
      placeholder: "https://john.blog/"
    message:
      label: Message
      placeholder: Your comment message
    submit: Submit Comment

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/esporo/steve. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Development

To set up your environment to develop this theme, run bundle install.

Your theme is setup just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in steve-for-jekyll.gemspec accordingly.

License

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