Project: watery - The Ruby Toolbox

Watery Theme for Jekyll

A bare-bones template to help you get started on your next blog or website.
Explore the docs »

View Demo · Report Bug · Request Feature

Quickstart (theme gem)

Use Watery as a reusable theme in your Jekyll site.

Add to your site Gemfile:

gem "jekyll", "~> 4.3"
gem "watery", "~> 0.1"

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
  gem "jekyll-paginate"
  gem "jekyll-sitemap"
end

Configure your site _config.yml:

theme: watery
plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-paginate
  - jekyll-sitemap

paginate: 5
paginate_path: "/page/:num/"

Build and serve:

bundle install
bundle exec jekyll serve

Install from RubyGems (optional)

Watery is published on RubyGems:

gem install watery

Ruby projects should prefer adding it to your site Gemfile (see Quickstart above).

About The Project

Watery is a minimalist, bare-bones theme for the popular JAMstack file-based CMS Jekyll that only uses the <80kb Water.css framework (hence the name!), while still following the best practices possible for accessibility and search-engine optimization.

I created this because I wasn't able to find an up-to-date starter/skeleton theme for Jekyll. Even the default theme, Minima, uses the large Bootstrap framework.

This project is aimed towards those curious about using Jekyll for the first time, and want to build from as close to scratch as possible. Alternatively, it still has all the features required for creating a hassle-free, informational website or blog in just a few clicks.

As of November 1st, 2020, with >70 posts on Watery, the website scores a perfect 100 in Performance, Accessibility, Best Practices, and SEO on an audit with Google Lighthouse.

For an example, you can view my blog, Journal.kim/ using this theme with the Writ.css framework.

New! Change the CSS framework with a single button, thanks to Dropin Minimal CSS.

Features

Despite Watery's minimalist nature, there are a few interesting features that have been added:

A fully customizable and empty _BLANK_config.yml to make getting up-and-running easy.
Having a _pages collection for easier organization.
Auto-generated links in navigation to all pages in _pages.
Auto-generated tags page that lists all tags used by all posts in chronological order.
An author bio at the end of each post. (Located in _inclues/author.html)
Full Rouge support for syntax code highlighting. (Currently using base16.solarized.light)
Auto-generated RSS feed, sitemap, accessibility features, and search-engine optimization.

Installation

Prerequisites

Jekyll requires the following:

Ruby version 3.0 or higher (3.2+ recommended)
RubyGems and Bundler
GCC and Make (build tools)

Note: Ruby 3 no longer bundles Webrick. This project declares webrick in the Gemfile, so bundle exec jekyll serve will work out of the box.

See Requirements for guides and details.

Instructions

Install all prerequisites.
Install the jekyll and bundler gems.

gem install jekyll bundler

Clone this repository.

git clone https://github.com/brennanbrown/watery.git

Change into your new directory.

cd watery

Install gems from the Gemfile.

bundle install

On macOS/Linux, this will regenerate Gemfile.lock for your platform (the repo previously contained a Windows-specific lockfile). Commit the updated lockfile.

Build the site and make it available on a local server.

bundle exec jekyll serve

Browse to http://localhost:4000

If you encounter any errors during this process, check that you have installed all the prerequisites in Requirements.

If you still have issues, see Troubleshooting.

Getting Started

Once you have Jekyll up-and-running, there are only a few steps needed to make this theme your own:

Fill out the _BLANK_config.yml configuration file and replace the current _config.yml
Remove the example_posts folder in _posts and start writing your own!
Modify or remove the pages in _pages to however you see fit.
(Optional) Modify or remove this README.md with information about your own project or blog.
(Optional) Modify the CSS files in the assets folder to customize the site.
(Optional) Remove switcher.js from the assets folder, choose another framework to use!

Optional extras

Optional link checking in CI with Lychee. See .github/workflows/link-check.yml and .lycheeignore.
Optional Sass scaffolding (no requirement): see assets/scss/sample.scss and notes in Gemfile comments.
Optional pagination with jekyll-paginate-v2 (not GitHub Pages–safe). See docs/PAGINATION.md.

Documentation

Changelog: docs/CHANGELOG.md
Theme gem guide (extraction/publish playbook): docs/GEM-THEME-GUIDE.md
Pagination options and guidance: docs/PAGINATION.md
Collections usage notes: docs/COLLECTIONS.md

Also see theme/README.md for gem-specific consumer instructions.

Roadmap

There are several features that I'm still planning to create and integrate, including:

Create a Theme Gem
Add easy and automatic buttons to "Deploy to Netlify", Heroku, etc.
Add Travis continious integration checks
Add additional documentation for creating custom collections and auto generated pages
Add the following files: robots.txt, asset-manifest.json, light.css.map
Add more example posts and articles

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.