Run Locally

• cd docs
• bundle install
• bundle exec jekyll serve or bundle exec jekyll serve --port 3000 --host 0.0.0.0 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

Description

A post with a large hero image.
Preview
Source

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

Post displaying highlighted code.
Preview
Source

A post displaying images with a variety of alignments.
Preview
Source

All posts grouped by year.
Preview
Source

All posts grouped by category.
Preview
Source

All posts grouped by tag.
Preview
Source

Category page.
Preview
Source

Listing of documents in grid view.
Preview
Source

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

      <li>
        <a rel="nofollow noopener" target="_blank" href="#search-changes">Search Changes</a>
      </li>
      <li>
        <a rel="nofollow noopener" target="_blank" href="#image-changes">Image Changes</a>
      </li>
      <li>
        <a rel="nofollow noopener" target="_blank" href="#development-changes">Development Changes</a>
      </li>
      <li>
        <a rel="nofollow noopener" target="_blank" href="#step-by-step">Step-by-Step</a>
      </li>
    </ol>
    

    4. Customization
       1. Overriding Includes and Layouts
       2. Customizing Sass (SCSS)
       3. Customizing JavaScript
    5. Font Awesome Icons
    6. Development
       1. JavaScript Build Script
    7. Contributing
    8. Credits
    9. License

    Installation

    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 http://USERNAME.github.io. 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 USERNAME.github.io 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
    • CHANGELOG.md
    • Gemfile
    • jekyll-theme-so-simple.gemspec
    • package.json
    • Rakefile
    • README.md
    • README-OLD.md
    • screenshot.png

    Upgrading

    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: