jekyll-oedipus-theme

Build a motherfucking website with Jekyll (patricide optional).

Gem Version

Screenshot

Oedipus rendered on a Thinkpad T60 in Firefox ESR

Installation

Add this line to your Jekyll site's Gemfile:

gem "jekyll-oedipus-theme"

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

theme: jekyll-oedipus-theme

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-oedipus-theme

Usage

Oedipus can be customized to a great extent in _config.yml, but if you want to override any part of the theme, you'll want a list of what's included.

_config.yml

All options for this theme are contained under the "site.oedipus" root. Therefore, the "rights" option listed below is actually "site.oedipus.rights".

  • rights: a string that goes into the copyright line in the page footer
  • license.text.name: a string identifying the license for your site's text
  • license.text.url: the URL of the license for your site's text
  • license.code.name: a string identifying the license for your site's code
  • license.code.url: the URL of the license for your site's code
  • made-with: a string indicating how the site was made.

The stylesheet for Oedipus is also configurable, and all style options are contained under "site.oedipus.style". The default colors were selected from Color Safe for accessibility. The dark theme takes each of these variables and applies the Sass invert() function to them.

  • bg-color: set background color
  • fg-color: set text color
  • link-color: set default link color
  • link-hover-color: change a link to this color on mouseover
  • link-active-color: change a link to this color when clicked
  • link-visited-color: change visited links to this color
  • border-thickness: set the thickness for borders
  • hr-border-thickness: set thickness for <hr> elements. Set this to half your intended value.
  • html-font-size: allows use of rem units for consistent scaling. Defaults to "medium".
  • body-margin: control distance between text and screen edges
  • content-font-size: Sets font-size for most text.
  • content-font-family: Sets the font-family for most text. Use this to define a custom font stack.
  • content-line-height: Sets separation between lines of text.
  • preformatted-font-size: Sets font-size for preformatted-text and code.
  • preformatted-font-family: Sets the font-family for most preformatted-text and code. Use this to define a custom font stack.
  • content-width: Sets the content width in <main> and <article>
  • content-centered: When true, Oedipus will horizontally center content.
  • compact-header: When true, Oedipus will place the site title and description inside the masthead's <h1>.
  • home-header-icon When true, any page assigned the "home" layout will show /assets/favicon.svg as part of the masthead.

Layouts

  • base.html: a wrapper layout that sets language and encoding, sets up a skip navigation link, and links to favicons, stylesheets, and feeds. Also provides a target for jekyll-seo-tag.
  • default.html: this wraps around page.html and post.html to provide headers, footers, and navigation.
  • home.html: for your site's home page. It provides custom headers and footers in case you don't want nav bars on your landing page.
  • page.html: for pages and other non-blog material. It wraps content inside a <main> element.
  • post.html: for blog posts. It wraps content inside an <article> element and provides a footer for subscription and contact info.

Includes

  • masthead.html: displays the site's title and description.
  • skip.html: implements a skip navigation link.
  • navbar.html: implements a navigation bar. It accepts "id", "label", and "source" arguments. Source is a data source accessible via site.data.
  • navlist.html: implements an unordered navigation list and takes the same arguments as navbar.html.
  • header.html: the default header for most pages and posts. Includes a navigation bar.
  • article-header.html: a sub-header for posts that contains the post title and summary
  • home-header.html: a header for the home page, sans nav bar.
  • footer.html: the default footer for most pages and posts. Includes a navigation bar.
  • article-footer.html: a sub-footer for posts that contains feed and contact links in lieu of a comments section
  • home-footer.html: a footer for the home page, sans nav bar.
  • posts-list.html: lists all posts as a set of <article> blocks.
  • recent-posts-list.html: lists the n most recent posts, where the "limit" argument = n.
  • posts-table.html: lists all posts in a table
  • recent-posts-table.html: lists the n most recent posts in a table, where the "limit" argument = n.
  • copyright.html: shows copyright info. used in footers.
  • license.html: shows license links for text and code. used in footers.
  • made-with.html: can be used to credit tools or represent a location. used in footers.

Sass

Oedipus' stylesheets are built with Sass, which is included with Jekyll.

  • assets/style.scss: wrapper file for the main stylesheet. It contains logic to override Sass variables with custom values from _config.yml.
  • assets/print.scss: wrapper file for the print stylesheet
  • _sass/variables.scss: contains variables with default values
  • _sass/main.scss: contains style definitions for the screen
  • _sass/skip.scss: implements Sass to hide the skip navigation link until tabbed into
  • _sass/dark.scss: provides dark mode support.

Data

Oedipus comes with two _data files: header-nav.yml and footer-nav.yml, which I use to build nav bars. They both contain entries in the following format:

- name: home
  url: /
  desc: front page

Assets

The only asset Oedipus provides, in addition to the stylesheets, is favicon.svg. You can and should generate your own. I recommend using Formito's generator. You can also use favicon.io, but you'll want to modify base.html and home-header.html since this site doesn't generate SVG.

Contributing

I built this theme for my own use. If you find this theme useful, you are welcome to it. If you wish to customize it, by all means fork it. I will fix bugs and consider pull requests at my own discretion.

Code of Conduct

This is not a professional project, and I am not interested in collaborating with others here. I am most certainly not interested in fostering "community", let alone providing an "open and welcoming environment". Nevertheless, I suppose a rudimentary and informal code of conduct is necessary.

  1. If you mess with me, you're banned.
  2. If you mess with other contributors on this project, you're messing with me.
  3. When in doubt, refer to rule 1.

(with apologies to Matthew Woodring Stover)

License

The theme is available as open source under the terms of the GNU GPL-3.0.

Commercial/Corporate/Government Use

I cannot prevent commercial use of this theme, but under no circumstance will I provide free technical support for commercial, corporate, or government projects. Issues and pull requests from people using Oedipus in a commercial, corporate, or government project will be summarily dismissed.

Note: I regard inclusion of this theme on a curated site supported by advertising as commercial use. Don't do it and then expect me to provide support to your visitors.