All jobs

Add Dark Mode to a Pelican Blog

Yes. An agent moves your Pelican theme's colours to custom properties, adds a prefers-color-scheme palette and a saved toggle, rebuilds the site 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 the theme before it touches a colour. In a Pelican site like getpelican/pelican-blog, pelicanconf.py sets THEME = "themes/notmyidea" and the theme's templates/base.html links one stylesheet, theme/css/{{ CSS_FILE }}, which Pelican's defaults resolve to main.css. That file imports reset.css, pygment.css, typogrify.css and fonts.css and then sets every colour by hand: a #F5F4EF page background on body, #000305 text, the #C74350 link red that also fills a hovered link, a black #000305 bar for #banner nav with #C74451 on its active item, white #fff boxes for #content and #featured, and #eee rules on .hentry. pygment.css carries the code colours on a #eee highlight background, and wide.css, the theme's alternate stylesheet, imports main.css and overrides only type and layout. There is no prefers-color-scheme query and no theme toggle anywhere under themes/.

It then builds the site once with the pinned tooling to know what it is changing: pelican content -s pelicanconf.py renders the blog's articles and pages with the notmyidea theme, and the agent opens the index, an article and the archives page in its own browser to record how each colour is used. With that map it rewrites main.css so the colours become custom properties declared on :root (--bg, --fg, --accent, --nav-bg, --panel, --rule), keeping the existing values as the light palette so the rendered site is pixel-for-pixel the same in light mode. A second block under @media (prefers-color-scheme: dark) sets a dark palette, and the same block is repeated under [data-theme="dark"] so a visitor's explicit choice beats the system setting. pygment.css gets a dark set of token colours in the same way, since a light code block on a dark page is the first thing readers notice.

The toggle is a small change to the theme's templates rather than a plugin. base.html gets a <button> inside #banner's nav with an aria-label, and a short inline script before the stylesheet link that reads localStorage and sets data-theme on <html> before the first paint, so a dark-mode reader never sees a white flash. The button's handler flips the attribute and stores the choice; with no stored choice the page follows the operating system. The script is inline so it works from make html and make publish alike with no new build step, and the agent keeps publishconf.py, which only sets SITEURL and DELETE_OUTPUT_DIRECTORY, untouched.

To check it, the agent rebuilds with the same command, confirms the article count in Pelican's summary line is unchanged, and screenshots the index and one article in its browser three ways: with the system preference light, with it dark, and with the toggle forced the other way. It reads the generated output/theme/css/main.css to confirm the properties and both palettes are present, and it checks the .social icon links in #extras, whose PNG icons come from themes/notmyidea/static/images/icons, still read against the dark panel, since image icons do not recolour with CSS. Those screenshots go into 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 Pelican blog. Read pelicanconf.py and publishconf.py to find the theme and the stylesheet it links, then read every CSS file under the theme's static directory and the base template. Build the site once and open the index, an article and the archives in a browser to see how each colour is used. Rewrite the stylesheet so its colours are custom properties on :root, keep the current values as the light palette, add a dark palette under a prefers-color-scheme media query and under a data-theme attribute, and give the code highlighting stylesheet a dark set of token colours. Add a toggle button to the base template with an inline script that applies a saved choice before first paint and otherwise follows the system setting. Rebuild, confirm the page count is unchanged, screenshot the index and an article in light, dark and forced modes, check that icon images still read on the dark panel, and open a pull request with the screenshots and the build output.",
  "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 the theme's main.css and pygment.css, adds the button and the inline script to base.html, and nothing under content/. Its description shows the Pelican summary line from the rebuild, lists each colour that became a property with its light and dark value, and attaches the screenshots of the index and an article in both modes so a reviewer can judge the palette without checking out the branch.

A reviewer looks at the dark values for the link red and the code block, which are taste rather than correctness, and at the one place image icons appear, and may ask for a lighter grey on the article rules. After merging, make publish renders the same HTML with the new stylesheet, and a reader whose system is set to dark gets the dark palette on first load with no flash, while anyone else sees the blog exactly as before.

Run it on every Pelican site in the terminal

A developer with make devserver running sends this body from their own machine with the blog'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 Pelican sites on the same theme 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 instead of opening a second set of pull requests.

Each run reads its own theme: a site whose theme already uses custom properties gets only the dark palette and the toggle, and a site on a different theme gets its colours mapped from that theme's stylesheet rather than from this one.

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

Why run it on Rush?

A dark mode is only as good as the colour audit behind it, and that audit is done by looking: which selectors set a background, which hover rule inverts a link, which code token turns invisible on a dark panel. The agent builds the site in its own sandbox, opens it in a real browser under both system preferences, takes the screenshots, and keeps every command and its output in the run's record, so the pull request carries proof rather than a promise.

It also fits the theme in front of it rather than a generic snippet: the stylesheet Pelican actually links through CSS_FILE, the alternate wide.css that imports it, the Pygments classes the Markdown codehilite extension emits with css_class set to highlight, and the image icons that CSS cannot recolour. Several blogs on several themes get several pull requests, each mapped from its own stylesheet.

Frequently asked questions

Will light mode look any different after the change?

No. The current colour values become the light palette, so the rendered page is the same in light mode. The agent rebuilds and compares screenshots of the index and an article before and after to confirm it.

Does it need a Pelican plugin or a new build step?

No. The change is CSS and one template, and the toggle script is inline in the base template, so make html and make publish work as they do now. Nothing is added to pelicanconf.py beyond what you already have.

What about code blocks?

The theme's pygment.css gets a dark set of token colours under the same media query and attribute, because a light code block on a dark page is the first thing readers notice. The agent screenshots an article that contains a code block in both modes.

Does the toggle remember my choice?

Yes. The choice is stored in the browser's localStorage and applied by the inline script before the stylesheet loads, so there is no flash on the next visit. With no stored choice the page follows the operating system's setting.

My site uses a different theme. Does this still apply?

Yes. The agent reads whichever theme THEME points at and maps that theme's stylesheet, so a theme with its own colour scheme gets its own palette rather than this one's. A theme that already declares custom properties needs only the dark values and the toggle.

More Pelican jobs

The same job on other stacks

Keep reading