All jobs

Add Dark Mode to a Zola Theme

Yes. An agent moves a Zola theme's colours into custom properties, adds a dark scheme with a toggle, ships its unused dark code theme, builds 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 where the colours live before it adds a scheme, because a dark mode is only as complete as the list of colours it replaces. In a theme like getzola/even, theme.toml sets min_version = "0.17.0" and the repository is its own demo site: config.toml at the root with compile_sass = true, generate_feed and the two taxonomies, content under content/, and a docs.yml workflow that publishes it with shalzz/zola-deploy-action@v0.17.2. The Sass is split by concern: _variables.scss holds $main-colour: #bb5649, $secondary-colour: #f8f5ec, $code-colour and a five-entry $theme-color-map nobody reads; _base.scss gives body the text colour #34495e on #fefefe; _header.scss repeats #34495e for the logo and menu; _main.scss uses #e6e6e6 borders and #757575 for muted text; _mobile.scss and _slideout.scss paint the mobile bar and menu white; _toc.scss uses a translucent cream. _syntax-charcoal.scss defines two mixins, light and dark, and site.scss includes only syntax.light, so a dark code theme exists in the repository and has never shipped. templates/index.html is the base layout, with an optional KaTeX block and the slideout script from a CDN, page.html and post_macros.html build posts, and static/even.js wires the mobile menu and the table of contents.

Building is the first check, and it tells the agent which Zola to use. The current release rejects the demo's generate_feed key, since the setting is generate_feeds now, then the highlight_code key, and then stops at the macro tag in post_macros.html; the deploy action pins 0.17.2, so the agent downloads that release and builds the demo as the workflow does, which produces fifteen pages and a single site.css with .z-code{color:#727373;background-color:#fff} and no prefers-color-scheme rule anywhere. zola check on the same build reports two external links in content/ that already answer 404, which the pull request notes without fixing.

The change is a layer of custom properties under the existing variables. In _variables.scss the agent declares :root with --bg, --fg, --fg-muted, --border, --panel and --code-bg set to the light values the files use today, and a [data-theme="dark"] block with a dark set; body, the header, the borders in _main.scss, the mobile bar, the slideout menu and the table of contents switch from literals to var(), while $main-colour stays the accent in both schemes because the theme's identity is that red. site.scss includes syntax.dark inside the dark selector so code blocks finally get the second mixin. In index.html a small <script> in <head> reads localStorage and prefers-color-scheme and sets data-theme before the first paint, a button in the header toggles it, and even.js gains the handler that stores the choice; a new extra.even_theme_toggle key, documented in the README beside even_menu and katex_enable, hides the button for a site that wants the system setting only.

To check it, the agent builds the demo with 0.17.2 again, compares the new site.css with the old one to list every rule that changed, serves public/ and opens the home page, a post with a code block and the about page in its own browser twice, once with dark colour scheme emulation and once without, and once more after clicking the toggle, taking a screenshot of each, and runs zola check to show the link report is unchanged. It also builds with the toggle key off to show the header renders as before.

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 Zola theme. Read theme.toml, config.toml, every file under sass/, templates/index.html, page.html and post_macros.html, static/even.js, the README and the deploy workflow first, and build the demo site with the Zola version the workflow pins, noting any key the current release no longer accepts. Replace the literal colours in the Sass with CSS custom properties declared on :root, add a dark set under a data-theme attribute, keep the accent colour in both schemes, and include the theme's existing dark syntax mixin under the dark selector. Set the attribute before first paint from localStorage and prefers-color-scheme, add a header toggle that stores the choice, and add an extra key that hides the toggle, documented in the README. Build again, diff the generated stylesheet, open the home page, a post with code and the about page in a browser in both schemes and after toggling, run zola check, and open a pull request with the commands, the diff summary and screenshots.",
  "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 changes sass/_variables.scss, _base.scss, _header.scss, _main.scss, _mobile.scss, _slideout.scss, _toc.scss and site.scss, templates/index.html, static/even.js, theme.toml, the demo config.toml and the README. Its description lists each colour literal and the property that replaced it, shows the stylesheet diff summary, the six screenshots, the zola check report, and the note on which config keys the current Zola release rejects.

A reviewer looks at the dark palette against the accent red, decides whether the toggle belongs in the header or the mobile bar, and whether to update the demo config for current Zola in the same change. After merging, a site on the theme follows the reader's system scheme on the next build, and the toggle remembers a choice per browser.

Run it on every Zola theme in the terminal

A developer with zola serve running sends this body from their own machine with the theme's repository in resources and reads the pull request from the console when the webhook on their API key reports the run. A team that maintains several themes sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own Sass: a theme that already uses custom properties gets only the dark set and the toggle, and a theme with inline syntax colours gets the class-based highlighting switch explained before the dark mixin can apply.

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

Why run it on Rush?

A dark mode done by hand is a hunt through partials for every hard-coded hex value, and the misses show up as a white mobile menu on a dark page. The agent reads every Sass file, builds the demo with the exact Zola the theme's workflow uses, diffs the generated stylesheet and looks at the pages in both schemes in its own browser, keeping every command, the diff and the screenshots in the run's record.

It also starts from what the theme already decided: an accent colour that stays, a dark syntax mixin that was written and never included, a config extra table where switches go. Several themes get the same treatment at once, each with its own list of replaced colours.

Frequently asked questions

Why build with Zola 0.17.2 rather than the current release?

Because the deploy workflow pins it, and because the current release rejects two keys in the demo config and the macro syntax in the templates before it gets to the Sass. The pull request lists those three stops so the maintainer can decide on an upgrade separately.

Will the page flash light before going dark?

No. The script that sets data-theme runs in <head> before the stylesheet applies, reading the stored choice first and the system preference second, so the first paint already has the right colours.

What about code blocks?

The theme ships _syntax-charcoal.scss with both a light and a dark mixin and only includes the light one. The change includes the dark mixin under the dark selector, so highlighted code switches with the page without a second stylesheet.

Can a site disable the toggle?

Yes. Setting even_theme_toggle = false under [extra] removes the button, and the page still follows the system scheme; the README documents the key next to the menu and KaTeX options.

More Zola jobs

The same job on other stacks

Keep reading