All jobs

Add Dark Mode to a Jekyll Site

Yes. An agent adds a dark palette, a navbar toggle and a system-preference default to a Jekyll theme's CSS variables, builds on both Jekyll versions and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the theme already handles colour. In a site built on daattali/beautiful-jekyll, every colour comes from _config.yml: page-col, text-col, link-col, hover-col, navbar-col, navbar-text-col, navbar-border-col, footer-col, footer-text-col, footer-link-col and footer-hover-col. assets/css/beautifuljekyll.css has Liquid front matter and turns those keys into CSS custom properties in a :root block (--page-col: {{ site.page-col | default: "#FFFFFF" }} and so on), with --mid-col: #808080 hard-coded beside them; the rest of the file uses the variables. _layouts/base.html loads Bootstrap 4.4.1 from a CDN, assets/css/bootstrap-social.css, beautifuljekyll.css and assets/js/beautifuljekyll.js; _includes/head.html adds site.site-css and page.css files and a mobile-theme-col meta tag; _includes/nav.html renders the navbar with a site.navbar-extra hook for extra includes and ends with {% include search.html %}, whose overlay has its own colours in the stylesheet. beautifuljekyll.js has an initNavbar function that reads the navbar's computed background colour, works out its brightness and switches between Bootstrap's navbar-dark and navbar-light classes once at load. pygment_highlights.css colours code blocks with fixed values. The gemspec is beautiful-jekyll-theme 6.0.1 on jekyll >= 3.9.3, and .github/workflows/ci.yml builds the site with Ruby 3.3 under appraisal for Jekyll 3.9.4 and 4.3.3.

The variables make the change small. The agent adds a second set of keys to _config.yml (dark-page-col, dark-text-col, dark-link-col, dark-navbar-col and the footer counterparts) with commented defaults, and in beautifuljekyll.css writes a [data-theme="dark"] block that reassigns the same custom properties from those keys, plus an @media (prefers-color-scheme: dark) block scoped to :root:not([data-theme="light"]) so a visitor who has never touched the toggle gets their system's choice. --mid-col and the search overlay's background get dark values in the same block, and pygment_highlights.css gets a [data-theme="dark"] variant for code blocks, because a white code box on a dark page is the first thing a reader notices.

A toggle needs three pieces, and each goes where the theme already expects it: a _includes/dark-mode-toggle.html button that nav.html includes when site.dark-mode-toggle is set, so a site that does not want it changes nothing; an inline script in head.html, before the stylesheets, that reads localStorage and sets data-theme on <html> so the page does not flash light before the choice applies; and a click handler in beautifuljekyll.js that flips the attribute, stores it and calls initNavbar again, since that function's brightness test ran against the light navbar colour and would otherwise leave the wrong Bootstrap class in place. The mobile-theme-col meta tag is updated by the same handler.

It runs bundle install, bundle exec appraisal install and bundle exec appraisal jekyll build --future as the workflow does, serves the result in the sandbox browser, and checks the home layout, a post, the search overlay and a code block in both modes before opening the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a dark mode to this Jekyll site. Read _config.yml, the gemspec, Gemfile, Appraisals, _layouts/base.html, _includes/head.html, _includes/nav.html, _includes/search.html, assets/css/beautifuljekyll.css, assets/css/pygment_highlights.css, assets/js/beautifuljekyll.js and .github/workflows/ci.yml first. Build on the theme's CSS custom properties: add dark counterparts of the colour keys to _config.yml with sensible defaults, a [data-theme=\"dark\"] block and a prefers-color-scheme default in the stylesheet, dark values for the search overlay and the code highlighting, an optional navbar toggle behind a config key, an inline script in the head that applies the stored choice before paint, and a click handler that stores the choice and re-runs the navbar brightness check. Run the same appraisal build the CI workflow runs for both Jekyll versions, check the home page, a post, the search overlay and a code block in both modes, and open a pull request that lists the new config keys and shows screenshots of both modes.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request touches _config.yml, assets/css/beautifuljekyll.css, assets/css/pygment_highlights.css, assets/js/beautifuljekyll.js, _includes/head.html and _includes/nav.html, and adds _includes/dark-mode-toggle.html. Its description lists the new keys with their defaults, shows screenshots of the home page and a post in both modes, and quotes the end of the two appraisal builds.

A reviewer checks three things: that a site with none of the new keys set builds and looks exactly as before, that the stored choice survives a reload without a flash, and that the navbar classes are right after a toggle. They also decide whether the default should follow the system preference or stay light, which is one line in the inline script.

From then on a site owner picks dark colours in _config.yml the same way they pick light ones, and the toggle is a config key away for sites that want it.

Run it on every site built on the theme

A team that maintains several sites on the same Jekyll theme sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own _config.yml: a site with a custom navbar-col gets a dark navbar colour derived from it, and a site that uses the theme as a gem rather than a fork gets the overrides placed in its own assets/ and _includes/ directories, which Jekyll prefers over the gem's.

Give the key a webhook_url and Rush POSTs run.completed to it when each turn ends, signed per Standard Webhooks, with data.session_url to read the pull request from. A follow-up on POST /o/{org}/sessions/{id}/messages, once the turn has finished, wakes the same sandbox to change a colour or move the toggle to the footer.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Dark mode on a theme is mostly checking: every include and stylesheet that hard-codes a colour, the code highlighting, the search overlay, a JavaScript brightness test that only runs once, and two Jekyll versions in CI. The agent builds the site both ways in its own sandbox, opens the pages in a browser in both modes, and the screenshots and build output come back with the pull request rather than being redone by the reviewer.

Because the change is driven by config keys, the same request works across every site on the theme; a team starts it once per repository and reviews small, uniform pull requests instead of porting a hand-made patch from site to site.

Frequently asked questions

Will sites that do not set any new key change?

No. Each dark key has a default in the stylesheet's default: filter, the toggle only renders when dark-mode-toggle is set, and the system-preference block only applies when the visitor's browser asks for dark. A site that wants to stay light in every case sets one key to turn the preference block off, and the pull request names it.

Why re-run the navbar brightness check?

initNavbar in beautifuljekyll.js reads the navbar's background colour once at load and chooses navbar-dark or navbar-light, which controls the toggler icon and link colours. After the palette flips, that choice is stale, so the click handler calls it again. Without this the hamburger icon can vanish against a dark navbar.

What about code blocks and the search overlay?

Both have their own colours outside the config variables: pygment_highlights.css for syntax colouring and the overlay rules in the main stylesheet. The agent adds dark variants for both, because they are the elements that stay bright when a theme only swaps page and text colours.

Does it work when the theme is installed as a gem?

Yes. Jekyll uses a file in the site before the same file in the theme gem, so the agent places the changed stylesheet, script and includes in the site's own directories and leaves the gem alone. The pull request says which files override the gem's so a later theme upgrade can be reconciled.

More Jekyll jobs

The same job on other stacks

Keep reading