Understanding Ruby’s Role in Jekyll and the Mediumish Theme

Jekyll is written in Ruby, and while basic site creation doesn't require in-depth Ruby knowledge, understanding the Ruby ecosystem is invaluable when customizing themes like Mediumish. Ruby enables you to create custom plugins, filters, and generators—features that can dramatically extend your blog’s capabilities beyond the out-of-the-box offering.

Where Ruby is Used in a Jekyll Site

• Plugins: Ruby-based scripts that extend Jekyll during build time.
• Gems: Packaged Ruby libraries that Jekyll uses, including themes like Mediumish.
• Liquid Filters: Many of Jekyll's filters are written in Ruby and can be extended or overridden.
• Configuration: Your _config.yml defines which Ruby gems and plugins are loaded.

Installing Ruby Locally for Jekyll Customization

If you want to develop Jekyll themes or build custom plugins for Mediumish, you'll need Ruby installed on your system. Here’s a simple setup process.

Installing Ruby on Linux/Mac:

brew install ruby # on macOS
sudo apt install ruby-full build-essential # on Ubuntu

Installing Ruby on Windows:

Use the official RubyInstaller at rubyinstaller.org which includes the MSYS2 toolchain needed to build native extensions.

Verifying Ruby and Bundler:

ruby -v
gem install bundler
bundle -v

Working with the Gem-based Mediumish Theme

When you install Mediumish as a gem, the actual theme files are hidden inside the Ruby environment. To override styles or layouts, you'll need to copy specific files into your local directory structure.

Steps to override gem-based theme files:

1. Locate the Mediumish gem folder using:

bundle show jekyll-theme-mediumish

2. Copy the necessary files (e.g. _layouts/post.html, _includes/) into your project directory.
3. Edit these files locally—Jekyll will prioritize your overrides.

Why override instead of edit in-place?

• Gems are managed externally—your changes could be lost on update.
• Keeping overrides local makes them easier to track in Git.

Creating Custom Ruby Plugins for Jekyll

When the Mediumish theme doesn't support a feature natively, you can build it yourself using a Ruby plugin. For example, you might want to generate a list of related posts based on content similarity rather than tags.

Example: Custom Related Posts Generator

module Jekyll
  class RelatedPostsGenerator < Generator
    def generate(site)
      site.posts.docs.each do |post|
        post.data['related'] = site.posts.docs
          .reject { |other| other == post }
          .sort_by { |other| -Jaccard.similarity(post.content, other.content) }
          .take(3)
      end
    end
  end
end

Save this in a file like _plugins/related_posts.rb. You may also need to define your own Jaccard similarity function or use a Ruby gem for NLP analysis.

Considerations:

• Plugins only work on local builds, not GitHub Pages without Actions.
• Use this approach only if you control your deployment pipeline.

Using Bundler to Manage Ruby Dependencies

Jekyll sites typically use a Gemfile to declare dependencies. This ensures consistent environments across machines and collaborators.

Sample Gemfile with Mediumish:

source "https://rubygems.org"

gem "jekyll", "~> 4.3.2"
gem "jekyll-theme-mediumish"
gem "webrick"

Install with:

bundle install

Why Bundler?

• Avoid version mismatch between local and CI environments.
• Quickly share dependencies across teams.
• Required for deploying Jekyll on GitHub Actions or Netlify.

Writing Custom Liquid Filters in Ruby

If the default Liquid filters don’t meet your needs (e.g., you want a filter to calculate reading time more precisely), you can write your own.

Example filter: Estimated Reading Time

module Jekyll
  module ReadingTime
    def reading_time(input)
      words_per_minute = 200
      words = input.split.size
      time = (words / words_per_minute.to_f).ceil
      "#{time} min read"
    end
  end
end

Liquid::Template.register_filter(Jekyll::ReadingTime)

Save as _plugins/reading_time.rb. Then use in your layout:

{{ page.content | reading_time }}

Deploying Custom Ruby-Powered Jekyll Blogs

Because GitHub Pages has a restricted set of whitelisted plugins, deploying Ruby-heavy Jekyll sites requires a CI/CD approach. GitHub Actions is the most convenient way to do this.

Steps to deploy with GitHub Actions:

1. Build the site using a Ruby container in Actions.
2. Run bundle exec jekyll build to generate the _site.
3. Push the _site folder to the gh-pages branch.

Alternative: Use Netlify

Netlify supports custom plugins and Ruby-based builds out of the box, making it a flexible alternative for blogs that rely heavily on Ruby logic.

Conclusion: Embracing Ruby to Unlock Full Power of Mediumish

Most users can use the Mediumish theme without touching Ruby, but understanding the Ruby foundation enables true customization and scalability. From custom filters to complete plugin systems, Ruby transforms Jekyll from a static site generator into a full-fledged content framework.

What’s next?

• Explore advanced Ruby libraries like Nokogiri for post-processing HTML.
• Integrate real-time data or API responses using Ruby plugins and caching.
• Develop reusable gem-based components across multiple Jekyll sites.

Mastering Ruby doesn’t just help you make a better blog—it allows you to build your own blogging framework tailored for your audience and goals.