No description
  • Python 35.9%
  • CSS 24.4%
  • Handlebars 20%
  • JavaScript 18.6%
  • Makefile 1.1%
Find a file
pulgamecanica fcd377fafb
All checks were successful
ci / theme (push) Successful in 4s
Release 0.1.42
2026-11-16 23:44:20 +01:00
.forgejo Release 0.1.1 2026-11-16 23:43:19 +01:00
assets Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
branding Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
docs Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
locales Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
partials Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
tools Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
.gitattributes Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
.gitignore Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
default.hbs Add README screenshots, branding, logo option; fix comments and mobile 2026-11-16 23:25:03 +01:00
docker-compose.yml Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
error.hbs Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
index.hbs Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
LICENSE Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
Makefile Release 0.1.1 2026-11-16 23:43:19 +01:00
package.json Release 0.1.42 2026-11-16 23:44:20 +01:00
page-me.hbs Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
page.hbs Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
post.hbs Add the Evil Penguin Ghost theme 2026-11-16 22:07:36 +01:00
README.md Release 0.1.1 2026-11-16 23:43:19 +01:00

Evil Penguin

Evil Penguin — a retro desktop theme for Ghost

Your Ghost site as an operating system: posts and pages open as draggable windows,
with a file manager, a mail app and a scroll-story "Me" app. Built for evil-penguin.com, free for anyone.

The empty desktop in every skin: Plain, Retro, Linux, Vista, Darwin, and Linux in light mode


Contents

Install

  1. Download evil-penguin-vX.Y.Z.zip from the latest release.
  2. In Ghost Admin go to Settings → Design & branding → Change theme → Upload theme and choose the zip.
  3. Click Activate.

Works with Ghost 5 and Ghost 6. Don't unzip the file, upload it as-is.

Customizing

A checklist to make the theme yours, roughly in order. Copy it into an issue to tick it off as you go. Details for each step are in Organizing your content and Theme settings.

Identity (Settings → General)

  • Site title and description: the title is the 🐧 menu name and the README window heading
  • Publication icon: e.g. branding/penguin-512.png
  • Publication language: en, de, es, pt or it (see Translations)
  • Publication logo, optional (Design & branding → Brand): replaces the pixel penguin in the menubar and on the boot screen. Leave it empty to keep the penguin
  • Accent color (Design & branding → Brand): used for links and highlights
  • Custom fonts, optional (Design & branding → Brand): override the heading and body fonts

Look (Settings → Design & branding → Customize)

  • Window skin: the default for new visitors (Retro, Linux, XP, Vista, Darwin, Plain)
  • Color scheme: Auto, Light or Dark
  • Reading font: Sans, Serif or Mono
  • Wallpaper, optional: one for every skin, or one per skin
  • Boot screen: on or off

Content

  • README: the home page lists your latest posts; nothing to create
  • Me app: a page with the slug me (title, excerpt, feature image, text)
  • Timeline: posts tagged #timeline (type the #!), dated to their year
  • Projects: posts tagged #project (type the #!); the feature image is the icon

⚠ Type the #. The tags are #project and #timeline, with the # in front. In Ghost's Tags field, type #project, not project. The # makes it an internal tag, which the theme looks for and visitors never see. A tag without the # is an ordinary public tag, and the post will just land in ~/blog.

  • Blog: any other post
  • Desktop icons for pages: turn on Feature this page
  • Legal pages: Privacy, Terms, Data deletion (Meta and other platforms ask for them)

Navigation (Settings → Navigation)

  • Primary: the File menu
  • Secondary: the 🐧 menu and the README footer (put the legal pages here)

Contact & members

  • Contact email: shows the Mail app
  • Members / subscriptions, optional (Settings → Membership): adds ★ Subscribe to the tray
  • Comments, optional (Settings → Membership): shown under posts

Analytics, optional

  • OpenPanel: enable it, add the client id and, if self-hosted, the API URL (see Analytics)
  • Mention it in your privacy policy

Check it

  • Open the site in each skin, light and dark, and on a phone
  • Turn on Plain and try it with only the keyboard

Features

Desktop

The desktop icons
Icon Opens
README.md The home window: your site description, projects, latest posts and legal links
Me The Me app (shown when a page with the slug me exists)
projects / blog The Files app on that folder
Mail The Mail app (shown when Contact email is set)
featured pages That page, in a window
settings The Settings app

Files app

The file manager in each skin

Folders open a file manager window instead of switching the desktop. It has a sidebar (projects, blog), a path bar and an item count, and the sidebar switches folders inside the same window. Every skin dresses it differently: a 1-bit list for Retro, Motif bevels for Linux, a blue task pane for XP, a soft navigation pane for Vista and a Finder-style sidebar for Darwin.

Mail app

The mail compose window

A compose window addressed to your Contact email. When the visitor presses Send, their own email app opens with the name, subject and message filled in. The theme stores and sends nothing, so it needs no server, but the visitor needs an email app on their device.

Me app

The Me app: the hero window, then the timeline windows stacking as you scroll

A full-screen story about you that blurs everything behind it:

  1. A hero window built from the page with the slug me: its title, excerpt, feature image and content.
  2. An index window listing every timeline entry. Clicking an entry jumps to it.
  3. A big banner with your site title.
  4. The timeline: every post with the internal tag #timeline, oldest first. Each post becomes a window titled YEAR · slug with its feature image, title and excerpt. If the post has content, it appears in a side window that slides in next to it. As you scroll, each window slides into place and stacks onto the one before.

Set each timeline post's publish date to the year you want it to show (for example 2017-01-01). Close the app with ✕ or Esc.

Windows

A post open in a window
  • Every internal link opens as a window, so you can keep several pages open next to each other.
  • Posts open as modal windows. Everything else dims and can't be clicked until you close the post with ✕ or Esc. Clicking the dimmed area makes the post window shake.
  • Drag a window by its title bar, resize it from the corner to any size, and double-click the title bar to maximize it.
  • Selection → Tile windows fills the free space next to the desktop icons. It picks the number of columns that gives each window a comfortable shape, stretches the last row so no gaps are left, and gives the active window the first slot.
  • Esc closes the active window. Window buttons only change their background on hover, so the ✕ never fades.
  • Every window has a real URL. Sharing /my-post/ opens the desktop with that window already open, and the back button works.
  • With JavaScript off, every page is still a normal, readable document. Search engines and link-preview crawlers see clean HTML.

Window skins

The README window in the Plain, Retro, Linux, Vista and Darwin skins, and Linux in light mode

There are six skins. Each one changes the windows, the desktop icons and the wallpaper. See every skin, feature by feature.

Skin Windows Icons & Files app Built-in wallpaper
Retro (default) 1-bit, hairline frame pixel art dotted grid
Linux Motif/CDE bevels, blue caption, light and dark palettes pixel art in X11 colours 70s stripes and an eye-patched penguin, light and dark versions
XP blue gradient caption smooth, yellow folders green hill where a penguin plants a pirate flag
Vista smoked glass smooth, glass hover aurora light ribbons
Darwin pinstripes, traffic lights smooth, blue folders soft colour circles behind a glossy torus covered in stickers
Plain none: a notepad with tabs, every link opens a new tab text only, images become their alt text none

The skins are original CSS homages to those systems and contain no vendor logos or copyrighted wallpapers. The site owner sets the default, and visitors can pick their own in the Settings app. Light and dark mode apply to every skin, Linux included.

Wallpapers

The built-in wallpapers

Every built-in wallpaper is original vector art, drawn by small Python scripts in tools/wallpapers/. Each one takes its composition from a well-known wallpaper, then adds an evil twist and a bit of animation:

Wallpaper Twist Animation
hills (XP) a penguin plants an open-source Jolly Roger on the crest realistic clouds drift endlessly across the sky and behind the hill, each at its own pace, receding and approaching at random; gusts of wind sweep the meadow from time to time; the flag waves; birds fly over
aurora (Vista) none, just the light none, it stays still
darwin (Darwin) + live torus stickers (Linux, sudo, rm -rf /…) stuck on a glossy donut the torus spins and tilts towards your pointer (WebGL, in desktop.js)
linux-light / linux-dark the penguin's eye is alive, and LINUX_ has a terminal cursor the eye follows your pointer, blinks now and then, squeezes shut when clicked and slowly turns bloodshot if you keep poking it (it heals); a gleam runs along the stripes; the cursor blinks
  • Everything stops for visitors who have reduce motion turned on.
  • The Linux penguin's eye is a tiny real element laid over the wallpaper. desktop.js repeats the browser's cover maths to keep it exactly on the drawn eye at any screen size. If you move the eye in linux.py, update EYE_X / EYE_Y / EYE_R in desktop.js to match. It only appears on the built-in Linux wallpaper, and it stops blinking on its own when animations are off.

Edit a script and run make wallpapers to regenerate them. clouds.py needs numpy and Pillow (with WebP support). The other scripts need only the standard library. The random detail (grass, clouds, ribbons) uses fixed seeds, so the output only changes when you change the code.

Reading view

The reading view with the serif font
  • Posts are laid out at a comfortable 68 characters per line.
  • Reading font: Sans (Atkinson Hyperlegible), Serif or Mono (Departure Mono).
  • Text size: S, M or L, chosen by the visitor.
  • Supports all Ghost cards, including the wide and full-width ones.

Settings app

The settings window

Visitors can change the skin, light or dark mode, animations on or off, the reading font and the text size. With animations off, every wallpaper freezes. The theme loads the same SVGs as file.svg#still, and a rule inside each file stops it. Window effects are turned off too. Their choices are saved in their own browser, and "Reset" goes back to your site's defaults.

Menubar and tray

Menu Items
🐧 Site description, README.md, secondary navigation (privacy, terms, …)
File Primary navigation, Close window, Close all
Edit Copy link, Settings…
Selection Cascade windows, Tile windows
Find Search… (Ghost's built-in search)
View ~/projects, ~/blog, Mail, Toggle light / dark

The tray on the right has the light/dark toggle, Mail ✉, Subscribe ★ (shown when members are enabled), Settings and a clock in the site's language. The menus are native <details> elements, so they also work without JavaScript.

Boot screen

The boot sequence

A short BIOS-style boot plays once per visit. Any key or click skips it. It never plays for visitors who have reduce motion turned on, and you can switch it off in the theme settings.

Mobile

The theme on a phone

On a phone the icons sit in a grid and windows open full-screen.

Also

  • A "kernel panic" page for 404s and other errors.
  • Ghost's custom fonts setting (Design → Brand) overrides the heading and body fonts.
  • Your brand accent color is used for links and highlights.
  • Comments show on posts when you enable them in Ghost.
  • All fonts and scripts are bundled with the theme. No CDNs and no third-party requests.

Organizing your content

⚠ Type the #. The tags are #project and #timeline, with the # in front. In Ghost's Tags field, type #project, not project. The # makes it an internal tag, which the theme looks for and visitors never see. A tag without the # is an ordinary public tag, and the post will just land in ~/blog.

You want… Do this in Ghost
A project in ~/projects Add the tag #project (with the #) to the post. Its feature image becomes the icon.
A post in ~/blog Nothing: every post without #project or #timeline is listed
The Me app Create a page with the slug me
A timeline entry in Me Add the tag #timeline (with the #) to a post and set its publish date to the year
The Mail app Theme settings → Contact email
A page icon on the desktop Open the page settings and turn on Feature this page.
Menu items under File Settings → Navigation → Primary
Legal links in the 🐧 menu and README Settings → Navigation → Secondary (Privacy, Terms, Data deletion, …)
A window title like about.md It comes from the post's slug.
Desktop wallpaper Theme settings → Wallpaper (all skins) or Wallpaper retro / linux / xp / vista / darwin (one skin)
Ghost Admin, Tags, Internal tags: #project and #timeline, stored with the slugs hash-project and hash-timeline

Theme settings

Find them under Settings → Design & branding → Customize.

The theme settings in Ghost Admin
Setting Default What it does
Window skin Retro Default window style (Retro, Linux, XP, Vista, Darwin, Plain)
Color scheme Auto Auto follows the visitor's OS; or force Light or Dark
Wallpaper — Used for every skin. Overrides everything below.
Wallpaper retro / linux / xp / vista / darwin — Wallpaper for one skin. If empty, that skin's built-in wallpaper is used.
Boot screen on Plays the boot sequence once per visit
Reading font (Post) Sans Default font for the reading view
Contact email — Shows the Mail app and addresses its messages
Enable OpenPanel off Opt-in analytics, see below
OpenPanel client id — Shown when OpenPanel is enabled
OpenPanel API URL — Your self-hosted API. Leave empty to use OpenPanel cloud.

Translations

The theme's own text (menus, the Settings, Files and Mail apps, the boot screen, the error page) ships in English, Deutsch, Español, Português and Italiano. Ghost picks the language from Settings → General → Publication language: set it to en, de, es, pt or it. Any other code falls back to English.

Your posts and pages aren't translated, since Ghost serves one language per site. To add a language, copy locales/en.json to locales/<code>.json, translate the values (keep the keys) and run make restart.

Analytics with OpenPanel (opt-in)

Analytics are off by default. The theme loads nothing until you turn them on.

  1. In OpenPanel, create a client and add your site's domain to it.
  2. In Ghost's theme settings, turn on Enable OpenPanel.
  3. Fill in the client id. For a self-hosted OpenPanel, also fill in the API URL (for example https://openpanel-api.example.com).

The tracker (op1.js) is bundled with the theme, so no script is loaded from openpanel.dev. Page views are tracked, including each window you open, because every window changes the URL. Outgoing links and data-track attributes are tracked too. OpenPanel is cookieless, but still mention it in your privacy policy.

Development

Requirements: Docker (with Compose), Node 20 or newer, and make.

make up        # Ghost on http://localhost:2368 with this folder mounted as the theme
               # first run: create the admin at /ghost, then activate "evil-penguin"
make restart   # after editing .hbs templates or package.json (CSS and JS reload on refresh)
make logs      # follow Ghost logs
make lint      # gscan, same check as CI
make zip       # dist/evil-penguin-vX.Y.Z.zip from the committed HEAD
make reset     # wipe the local Ghost content
make wallpapers # regenerate the SVG wallpapers
make           # list all targets

Layout

default.hbs            page shell: menubar, desktop icons, app templates, scripts
index.hbs              home (README window) and archives (ls window)
post.hbs / page.hbs    a single window with the reading view (posts are modal)
page-me.hbs            the Me app (page with slug "me" + #timeline posts)
error.hbs              kernel panic
partials/
  window.hbs           window chrome, used as a block partial: {{#> window name="x.md" modal=true}}
  article.hbs          the reading view
  desktop.hbs          desktop icons
  files.hbs  mail.hbs  settings.hbs   app windows (<template>s)
  menubar.hbs  boot.hbs  openpanel.hbs  icon.hbs
  ico/*.hbs            desktop icons: pixel + smooth variant, the skin picks one
  px/*.hbs             pixel-art SVG icons
locales/*.json         en, de, es, pt, it
assets/images/wallpapers/  built-in wallpapers (generated, see tools/wallpapers)
tools/wallpapers/      wallpaper generators (Python; clouds.py also uses numpy + Pillow); `make wallpapers`
assets/css/screen.css  tokens, skins, reading view
assets/js/desktop.js   window manager (vanilla JS, no build step)

How windows work

desktop.js intercepts clicks on internal links. It fetches the page Ghost already renders, takes its [data-window] element and adds it to the desktop. A page that has no [data-window] (RSS, members pages and so on) opens normally. App windows that aren't Ghost pages (Settings, Files, Mail) are <template id="ep-app-NAME"> elements opened with data-app="NAME" (and an optional data-arg). Windows marked data-modal (posts, Me) are moved into a native <dialog> and opened with showModal(), so the browser makes everything behind them inert, handles Esc, and draws the dimmed backdrop.

Releasing

CI runs on Forgejo Actions (.forgejo/workflows/ci.yml) and uses the same Makefile:

  • Every push and pull request: make lint, then make zip.
  • Tag vX.Y.Z: make release checks that the tag matches the version in package.json, builds the zip and creates a Forgejo release with the zip attached.
# 1. bump "version" in package.json (e.g. 0.2.0), commit and push main
# 2. tag that commit with the same version and push the tag:
make tag            # = git tag v0.2.0 && git push origin v0.2.0

The tag must equal v + the version in package.json, so let make tag write it. Don't run make release yourself: CI runs it when the tag arrives.

The workflow uses Forgejo's automatic token. If that token isn't allowed to create releases, add a repository secret called RELEASE_TOKEN with repository write access. The job runs on runners labelled docker, so change runs-on if your runner uses a different label.

docs/, tools/, .forgejo/, the Makefile and docker-compose.yml are left out of the zip (see .gitattributes).

Credits & licenses

Wallpaper inspirations

The wallpapers are original drawings made for this theme. They borrow the composition and mood of these works, not their pixels. Thanks to their authors:

  • hills (XP): Bliss, the green-hill photograph by Charles O'Rear used as the Windows XP default wallpaper, and its fan-made 4K remakes (reference).
  • aurora (Vista): the Windows Vista Aurora default wallpaper (reference).
  • linux-light / linux-dark: a late-1970s inspired Linux wallpaper shared on r/linux, and its dark resize (light, dark). Tux, the Linux penguin, was created by Larry Ewing; the penguin here is drawn from scratch.