Skip to main content
  1. All Posts/


Tools Open Source Sync WordPress

Run Locally

  • cd docs
  • bundle install
  • bundle exec jekyll serve or bundle exec jekyll serve --port 3000 --host on Gitpod

Theme Cusomization

Overriding Includes and Layouts

Theme files can be overridden by placing a file with the same name into your project’s _includes or _layouts directory. For instance:

  • To add another social sharing button to _includes/social-share.html, create an _includes directory in your project, copy _includes/social-share.html from So Simple’s gem folder to <your_project>/_includes and edit that file.

ProTip: to locate the theme’s files on your computer run bundle show jekyll-theme-so-simple. This returns the location of the gem-based theme files.

So Simple Jekyll Theme

So Simple is a simple Jekyll theme for your words and pictures. Built to provide:

  • A variety of layouts with clean and readable typography.
  • Microformats markup to make post content machine-readable and discoverable.
  • Disqus Comments and Google Analytics support.
  • SEO best practices via Jekyll SEO Tag.
  • Options to customize the theme and make it your own.

If you enjoy this theme, please consider supporting me for developing and maintaining it.

See what’s new in the CHANGELOG.
📘 v2 documentation.

Sample Pages


A post with a large hero image.

A post with a variety of common HTML elements showing how the theme styles them.

Post displaying highlighted code.

A post displaying images with a variety of alignments.

All posts grouped by year.

All posts grouped by category.

All posts grouped by tag.

Category page.

Listing of documents in grid view.

Additional sample posts can be view on the demo site. Source files for these (and the entire demo site) can be found in /docs folder.

Table of Contents

  1. Installation

    1. Ruby Gem Method
    2. GitHub Pages Method

      1. Remove the Unnecessary
  2. Upgrading

    1. Ruby Gem
    2. Remote Theme
    3. Use Git
    4. Update Files Manually
  3. Structure

    1. Starting Fresh
    2. Starting from jekyll new
  4. Configuring

    1. Site Locale
    2. Site URL
    3. Site Base URL
    4. Date Format
    5. Reading Time
    6. Mathematics
    7. Google Fonts
    8. Pagination
    9. Search
    10. Taxonomy Pages
    11. Comments (via Disqus)
    12. Google Analytics
    13. Other
  5. Layouts

    1. layout: default
    2. layout: post
    3. layout: page
    4. layout: home
    5. layout: posts
    6. layout: categories
    7. layout: tags
    8. layout: collection
    9. layout: category
    10. layout: tag
    11. layout: search
  6. Images
  7. Theme Text
  8. Navigation
  9. Author
  10. Footer

    1. Footer Links
    2. Copyright Text
  11. Helpers

    1. Responsive Embed
    2. Table of Contents
  12. Migration Guide

    1. Global Changes
    2. Browser Support
    3. Configuration Changes

      1. Locale Changes
      2. Owner Changes
      3. Google Analytics Changes
      4. Disqus Comments Changes
    4.   <li>
          <a rel="nofollow noopener" target="_blank" href="#search-changes">Search Changes</a>
          <a rel="nofollow noopener" target="_blank" href="#image-changes">Image Changes</a>
          <a rel="nofollow noopener" target="_blank" href="#development-changes">Development Changes</a>
          <a rel="nofollow noopener" target="_blank" href="#step-by-step">Step-by-Step</a>
    5. Customization

      1. Overriding Includes and Layouts
      2. Customizing Sass (SCSS)
      3. Customizing JavaScript
    6. Font Awesome Icons
    7. Development

      1. JavaScript Build Script
    8. Contributing
    9. Credits
    10. License


    If you’re running Jekyll v3.5+ and self-hosting you can quickly install the theme as a Ruby gem. If you’re hosting with GitHub Pages you can install as a remote theme or directly copy all of the theme files (see structure below) into your project.

    Ruby Gem Method

    1. Add this line to your Jekyll site’s Gemfile (or create one):

      gem "jekyll-theme-so-simple"
    2. Add this line to your Jekyll site’s _config.yml file:

      theme: jekyll-theme-so-simple
    3. Then run Bundler to install the theme gem and dependencies:

      bundle install

    GitHub Pages Method

    GitHub Pages has added full support for any GitHub-hosted theme.

    1. Replace gem "jekyll" with:

      gem "github-pages", group: :jekyll_plugins
    2. Run bundle update and verify that all gems install properly.
    3. Add remote_theme: "mmistakes/so-simple-theme" to your
      _config.yml file. Remove any other theme: or remote_theme: entries.

    Note: Your Jekyll site should be viewable immediately at If it’s not, you can force a rebuild by pushing empty commits to GitHub (see below for more details).
    If you’re hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than and create a gh-pages branch off of master. For more details on how this works, check GitHub’s documentation.

    Remove the Unnecessary

    If you forked or downloaded the so-simple-theme repo you can safely remove the following files and folders:

    • .github
    • docs
    • example
    • .editorconfig
    • .gitattributes
    • banner.js
    • Gemfile
    • jekyll-theme-so-simple.gemspec
    • package.json
    • Rakefile
    • screenshot.png


    If you’re using the Ruby Gem or remote theme versions of So Simple, upgrading is fairly painless.
    To check which version you are currently using, view the source of your built site and you should something similar to: