Allow skins to be defined and customized easily (jekyll#336)

Merge pull request 336

README.md

@@ -72,10 +72,15 @@ Refers to snippets of code within the `_includes` directory that can be inserted
 
 Refers to `.scss` files within the `_sass` directory that define the theme's styles.
 
-  - `minima.scss` — The core file imported by preprocessed `css/style.scss`, it defines the variable defaults for the theme and also further imports sass partials to supplement itself.
-  - `minima/_base.scss` — Resets and defines base styles for various HTML elements.
-  - `minima/_layout.scss` — Defines the visual style for various layouts.
-  - `minima/_syntax-highlighting.scss` — Defines the styles for syntax-highlighting.
+  - `minima-classic.scss` — The core file imported by preprocessed `css/style.scss`, it defines the variable defaults for
+    the "classic" skin of the theme.
+  - `minima/initialize.scss` — A component that defines the theme's *skin-agnostic* variable defaults and sass partials.
+  - `minima/custom-variables.scss` — A hook that allows overriding variable defaults and mixins. (*Note: Cannot override styles*)
+  - `minima/custom-styles.scss` — A hook that allows overriding styles. (*Note: Cannot override variables*)
+  - `minima/_base.scss` — Sass partial for resets and defines base styles for various HTML elements.
+  - `minima/_layout.scss` — Sass partial that defines the visual style for various layouts.
+
+Refer the [skins](#skins) section for more details.
 
 
 ### Assets
@@ -105,32 +110,18 @@ theme: minima
 To override the default structure and style of minima, simply create the concerned directory at the root of your site, copy the file you wish to customize to that directory, and then edit the file.
 e.g., to override the [`_includes/head.html `](_includes/head.html) file to specify a custom style path, create an `_includes` directory, copy `_includes/head.html` from minima gem folder to `<yoursite>/_includes` and start editing that file.
 
-The site's default CSS has now moved to a new place within the gem itself, [`assets/css/style.scss`](assets/css/style.scss). To **override the default CSS**, the file has to exist at your site source. Do either of the following:
-- Create a new instance at site source.
-  - Create a new file at `<your-site>/assets/css/style.scss`
-  - Add the frontmatter dashes, and
-  - Add `@import "minima";`
-  - Add your custom CSS.
-- Download the file from this repo
-  - Create  a new file at `<your-site>/assets/css/style.scss`
-  - Copy the contents at [assets/css/style.scss](assets/css/style.scss) onto the `css/style.scss` you just created, and edit away!
-- Copy directly from minima gem
-  - Go to your local minima gem installation directory ( run `bundle show minima` to get the path to it ).
-  - Copy the `assets/` folder from there into the root of `<your-site>`
-  - Change whatever values you want, inside `<your-site>/assets/css/style.scss`
-
-
-When you override only a minima-sass-partial, it is not automatically imported because we're still importing the `minima.scss` within the theme-gem and that subsequently imports the partials with respect to itself, i.e. partials within the gem. Hence you should either include a *copy of `minima.scss` from the gem* inside the `_sass` directory at source or the overriding `/assets/css/style.scss` file should explicitly import the edited partial. :
-  e.g. To have an **edited** `_syntax-highlighting.scss` be rendered, you should either have
-
-```sass
-/* <your-site>/assets/css/style.scss */
-
-@import "minima";
-@import "minima/syntax-highlighting";
-```
-or
-your `<your-site>/_sass/` should look like:
+The site's default CSS has now moved to a new place within the gem itself, [`assets/css/style.scss`](assets/css/style.scss).
+
+In Minima 3.0, if you only need to customize the colors of the theme, refer to the subsequent section on skins. To have your
+*CSS overrides* in sync with upstream changes released in future versions, you can collect all your overrides for the Sass
+variables and mixins inside a sass file placed at `_sass/minima/custom-variables.scss` and all other overrides inside a sass file
+placed at path `_sass/minima/custom.scss`.
+
+You need not maintain entire partial(s) at the site's source just to override a few styles.
+
+#### Skins
+
+Minima 3.0 supports defining and switching between multiple color-palettes (or *skins*).
 
 ```
 .
@@ -139,15 +130,33 @@ your `<your-site>/_sass/` should look like:
     └── _syntax-highlighting.scss
 ```
 
-To have your CSS overrides in sync with upstream changes released in future versions, collect all your overrides into a single partial sass-file and then import that partial after importing minima, like so:
 
-```sass
-/* <your-site>/assets/css/style.scss */
+A skin is a Sass file named in the format `minima-*` and is the core file imported by the `assets/css/style.scss`. It defines the
+variable defaults related to the "color" aspect of the theme and imports two components:
+
+  - `minima/initialize.scss` &mdash; Defines the theme's *skin-agnostic* variable defaults and sass partials for styles.
+  - `minima/custom-styles.scss` &mdash; A hook for overriding the predefined styles. (*Note: Cannot override variables*)
 
-@import "minima";
-@import "my_overrides";
+A skin also embeds the Sass rules related to syntax-highlighting since that is primarily related to color and has to be adjusted
+in harmony with the current skin.
+
+The default color palette for Minima is defined within `_sass/minima-classic.scss`. To switch to another available skin, simply
+declare it in the site's config file. For example, to activate `_sass/minima-sunrise.scss` as the skin, the setting would be:
+
+```yaml
+minima:
+  skin: sunrise
 ```
 
+As part of the migration to support skins, some existing Sass variables have been retired and some **have been redefined** as
+summarized in the following table:
+
+Minima 2.0      | Minima 3.0
+--------------- | ----------
+`$brand-color`  | `$link-base-color`
+`$grey-*`       | `$brand-*`
+`$orange-color` | *has been removed*
+
 
 ### Customize navigation links
 

_sass/minima/_syntax-highlighting.scss → _sass/minima-classic.scss

@@ -1,14 +1,27 @@
-/**
- * Syntax highlighting styles
- */
-.highlight {
-  background: #fff;
-  @extend %vertical-rhythm;
+@charset "utf-8";
+
+$brand-color:           #828282 !default;
+$brand-color-light:     lighten($brand-color, 40%) !default;
+$brand-color-dark:      darken($brand-color, 25%) !default;
+
+$text-color:            #111 !default;
+$background-color:      #fdfdfd !default;
+$code-background-color: #eef !default;
+
+$link-base-color:       #2a7ae2 !default;
+$link-visited-color:    darken($link-base-color, 15%) !default;
 
-  .highlighter-rouge & {
-    background: #eef;
-  }
+$table-text-color:      lighten($text-color, 18%) !default;
+$table-zebra-color:     lighten($brand-color, 46%) !default;
+$table-header-bg-color: lighten($brand-color, 43%) !default;
+$table-header-border:   lighten($brand-color, 36%) !default;
+$table-border-color:    $brand-color-light !default;
 
+
+// Syntax highlighting styles should be adjusted appropriately for every "skin"
+// ----------------------------------------------------------------------------
+
+.highlight {
   .c     { color: #998; font-style: italic } // Comment
   .err   { color: #a61717; background-color: #e3d2d2 } // Error
   .k     { font-weight: bold } // Keyword
@@ -69,3 +82,9 @@
   .vi    { color: #008080 } // Name.Variable.Instance
   .il    { color: #099 } // Literal.Number.Integer.Long
 }
+
+// import skin-agnostic styles and override
+@import
+  "minima/initialize",
+  "minima/custom-styles"
+;

_sass/minima/_base.scss

@@ -104,11 +104,11 @@ h1, h2, h3, h4, h5, h6 {
  * Links
  */
 a {
-  color: $brand-color;
+  color: $link-base-color;
   text-decoration: none;
 
   &:visited {
-    color: darken($brand-color, 15%);
+    color: $link-visited-color;
   }
 
   &:hover {
@@ -130,8 +130,8 @@ a {
  * Blockquotes
  */
 blockquote {
-  color: $grey-color;
-  border-left: 4px solid $grey-color-light;
+  color: $brand-color;
+  border-left: 4px solid $brand-color-light;
   padding-left: $spacing-unit / 2;
   @include relative-font-size(1.125);
   letter-spacing: -1px;
@@ -150,9 +150,9 @@ blockquote {
 pre,
 code {
   @include relative-font-size(0.9375);
-  border: 1px solid $grey-color-light;
+  border: 1px solid $brand-color-light;
   border-radius: 3px;
-  background-color: #eef;
+  background-color: $code-background-color;
 }
 
 code {
@@ -170,6 +170,15 @@ pre {
   }
 }
 
+.highlight {
+  background: $code-background-color;
+  @extend %vertical-rhythm;
+
+  .highlighter-rouge & {
+    background: $code-background-color;
+  }
+}
+
 
 
 /**
@@ -210,11 +219,11 @@ pre {
  */
 
 .orange {
-  color: $orange-color;
+  color: #f66a0a;
 }
 
 .grey {
-  color: $grey-color;
+  color: #828282;
 }
 
 .svg-icon {
@@ -234,23 +243,22 @@ table {
   margin-bottom: $spacing-unit;
   width: 100%;
   text-align: $table-text-align;
-  color: lighten($text-color, 18%);
+  color: $table-text-color;
   border-collapse: collapse;
-  border: 1px solid $grey-color-light;
+  border: 1px solid $table-border-color;
   tr {
     &:nth-child(even) {
-      background-color: lighten($grey-color-light, 6%);
+      background-color: $table-zebra-color;
     }
   }
   th, td {
     padding: ($spacing-unit / 3) ($spacing-unit / 2);
   }
   th {
-    background-color: lighten($grey-color-light, 3%);
-    border: 1px solid darken($grey-color-light, 4%);
-    border-bottom-color: darken($grey-color-light, 12%);
+    background-color: $table-header-bg-color;
+    border: 1px solid $table-header-border;
   }
   td {
-    border: 1px solid $grey-color-light;
+    border: 1px solid $brand-color-light;
   }
 }

_sass/minima/_layout.scss

@@ -2,8 +2,8 @@
  * Site header
  */
 .site-header {
-  border-top: 5px solid $grey-color-dark;
-  border-bottom: 1px solid $grey-color-light;
+  border-top: 5px solid $brand-color-dark;
+  border-bottom: 1px solid $brand-color-light;
   min-height: $spacing-unit * 1.865;
   line-height: $base-line-height * $base-font-size * 2.25;
 
@@ -24,7 +24,7 @@
 
   &,
   &:visited {
-    color: $grey-color-dark;
+    color: $brand-color-dark;
   }
 }
 
@@ -33,7 +33,7 @@
   top: 9px;
   right: $spacing-unit / 2;
   background-color: $background-color;
-  border: 1px solid $grey-color-light;
+  border: 1px solid $brand-color-light;
   border-radius: 5px;
   text-align: right;
 
@@ -50,7 +50,7 @@
     text-align: center;
 
     > svg path {
-      fill: $grey-color-dark;
+      fill: $brand-color-dark;
     }
   }
 
@@ -122,7 +122,7 @@
  * Site footer
  */
 .site-footer {
-  border-top: 1px solid $grey-color-light;
+  border-top: 1px solid $brand-color-light;
   padding: $spacing-unit 0;
 }
 
@@ -139,7 +139,7 @@
 
 .footer-col-wrapper {
   @include relative-font-size(0.9375);
-  color: $grey-color;
+  color: $brand-color;
   margin-left: -$spacing-unit / 2;
   @extend %clearfix;
 }
@@ -214,7 +214,7 @@
 
 .post-meta {
   font-size: $small-font-size;
-  color: $grey-color;
+  color: $brand-color;
 }
 
 .post-link {
@@ -282,7 +282,7 @@
     a {
       display: block;
       padding: $spacing-unit / 4;
-      border: 1px solid $grey-color-light
+      border: 1px solid $brand-color-light
     }
     &:hover .svg-icon { fill: currentColor; }
   }

_sass/minima/custom-styles.scss

@@ -0,0 +1,2 @@
+// Placeholder to allow defining custom styles that override everything else.
+// (Use `_sass/minima/custom-variables.scss` to override variable defaults)

_sass/minima/custom-variables.scss

@@ -0,0 +1 @@
+// Placeholder to allow overriding predefined variables smoothly.

_sass/minima.scss → _sass/minima/initialize.scss

@@ -2,22 +2,14 @@
 
 // Define defaults for each variable.
 
-$base-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
+$base-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Segoe UI Symbol", "Segoe UI Emoji", "Apple Color Emoji", Roboto, Helvetica, Arial, sans-serif !default;
 $base-font-size:   16px !default;
 $base-font-weight: 400 !default;
 $small-font-size:  $base-font-size * 0.875 !default;
 $base-line-height: 1.5 !default;
 
 $spacing-unit:     30px !default;
 
-$text-color:       #111 !default;
-$background-color: #fdfdfd !default;
-$brand-color:      #2a7ae2 !default;
-
-$grey-color:       #828282 !default;
-$grey-color-light: lighten($grey-color, 40%) !default;
-$grey-color-dark:  darken($grey-color, 25%) !default;
-$orange-color:     #f66a0a !default;
 $table-text-align: left !default;
 
 // Width of the content area
@@ -48,9 +40,9 @@ $on-large:         $on-laptop !default;
   font-size: $base-font-size * $ratio;
 }
 
-// Import partials.
+// Import pre-styling-overrides hook and style-partials.
 @import
-  "minima/base",
-  "minima/layout",
-  "minima/syntax-highlighting"
+  "custom-variables", // Hook to override predefined variables.
+  "base",             // Defines element resets.
+  "layout"            // Defines structure and style based on CSS selectors.
 ;

assets/css/style.scss

@@ -2,4 +2,4 @@
 # Only the main Sass file needs front matter (the dashes are enough)
 ---
 
-@import "minima";
+@import "minima-{{ site.minima.skin | default: 'classic' }}";