# 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 Rush](https://cloud.getrush.ai/run/add-dark-mode/zola/). Opens 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`

```json
{
  "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.

## 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

- [Add Giscus Comments to a Zola Blog](https://getrush.ai/run/add-giscus-comments/zola/)
- [Add a Second Language to a Zola Site](https://getrush.ai/run/add-i18n/zola/)
- [Show Last Updated Dates on a Zola Blog](https://getrush.ai/run/add-last-updated-dates/zola/)

## The same job on other stacks

- [Add Dark Mode to an Angular App](https://getrush.ai/run/add-dark-mode/angular/)
- [Add Dark Mode to a Blazor Web App](https://getrush.ai/run/add-dark-mode/blazor/)
- [Add Dark Mode to a Chrome Extension Popup](https://getrush.ai/run/add-dark-mode/chrome-extension/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
