If you’re not interested in understanding the problem, skip to the solution.

Problem

I had just finished deploying my website using GitHub Pages and Jekyll. It looked simple and minimal, which is expected of a default theme named “minima.” However, when I went to check how it looked from my phone, I was blinded by the brightness of the “classic” or default light theme. I don’t want anyone checking my website and thinking I was some psychopath or serial killer so the first order of business was to politely force everyone to view the site in dark mode, even without an add-on like Dark Reader.

Problem 2

It turns out there is a very simple method to changing the theme to dark mode as described here. All you would have to do is add the following two lines in the _config.yaml:

minima:
  skin: dark

Yeah that didn’t work. This “feature” is new as of minima version 3.0, which is not supported by GitHub Pages. This reference actually shows that the version used by GitHub Pages is 2.5.1 (from 2019!).

I also tried a different method using a jekyll-remote-theme but that did not work either and defaulted back to the classic/light theme.

And now we reach a cross-roads; there are a couple possible solutions that I’ll briefly describe:

  • manually modify sass (scss) files, potentially copying over the dark mode sass files from version 3.0 to my local 2.5.1 version
    • Pro: possibly the simplest
    • Con: there might be other compatibility issues if there were new variables or features in 3.0 that 2.5.1 doesn’t have
  • use a completely different theme that has a supported dark mode
    • Pro: if it works, it works
    • Con: I liked the minima theme and because it was Jekyll’s default, I knew it would have the most development and support going forward
  • manually run the Jekyll process instead of relying on GitHub Pages default actions
    • Pro: I’ll have the most control over the build and deployment process
    • Con: I have to figure out the manual build and deployment process

I ended up going with the first solution, which is described below.

Solution

Starting from the bottom, here are some definitions that are grossly simplified (do a Google search for more accurate descriptions):

  • CSS: Cascading Style Sheet is the file that defines the style (colors, spacing, orientation, etc) of a webpage (html)
  • SASS: Syntactically Awesome Style Sheet is a higher-level instantiation of CSS that allows for templating CSS files, making it easier to deal with CSS files in an inherited way
  • SCSS: SASSy CSS is the file extension and format most commonly used for SASS; it’s also used by Jekyll

The general flow is that the user will create SCSS and/or CSS files, use SASS to process those files and output a CSS file, and then use the output CSS file for their webpage(s).

The main difficulty is that the default variable names, files, and their locations differ slightly between versions 2.5.1 and 3.0. For our purposes, we will use files from both versions and make them play nice with each other. Our main reference will be the v2.5.1 commit and its documentation.

Within your sites directory (not _sites, usually docs by default), create the following sub-directory structure (“/” at the end indicates directory):

- docs/
  - assets/
    - main.scss (use 2.5.1 conventions)
  - _sass/
    - minima.scss (use 2.5.1 conventions but reference 3.0 initialize.scss and explicitly reference skins/dark.scss)
    - minima/ (use 3.0 files)
      - _base.scss
      - _layout.scss
      - custom-styles.scss
      - custom-variables.scss
      - initialize.scss
      - skins/
        - auto.scss
        - classic.scss
        - dark.scss

Steps

  1. Use main.scss from 2.5.1 and place in docs/assets/main.scss, copy over from here or where your default is stored locally within the gem directory (you can figure out the location using bundle show minima); it should only be importing “minima”, which will be the next file
  2. Use minima.scss from 2.5.1 and place in docs/_sass/minima.scss, copy over from here and replace the 3 imports with minima/skins/dark and minima/initialize; the reason we are not using the fancy templating method with curly braces here is that either the Jekyll version or minima version used by GitHub Pages does not support it. I’ve opted to hard-code in the reference to dark.scss instead for simplicity
  3. Copy over the entire _sass/minima/ directory from the 3.0 minima directory to include the 5 scss files and the entire skins/ directory with 3 scss files; because we are using the 2.5.1 minima.scss file and “inheriting” any new variable names and configurations from the 3.0 initialize.scss file, that seemed to fix the initial errors I was getting with unrecognized variable names; you can do this by git cloneing the entire repo and recursively copying over the specific directory, you can take a more manual approach and wget the raw url for each file, or, if you’re in a rush, you could copy and paste the contents directly
  4. Now run bundle exec jekyll serve or whatever method you use in your local setup to verify that dark mode is now working for your minima theme! You may need to do a hard-refresh (hold shift and click the refresh button in most browsers) and/or erase cookies/site data to get rid of the old light/classic theme cache
  5. Don’t forget to push your changes to your GitHub repository and verify again at your respective url

Final Words

If you had any trouble or if you think I made a mistake, visit the repo for this site here and submit an issue or pull request. I’ll be happy to help you out if you’re having trouble.