RetroCSS 9x

RetroCSS 9x is a Win9x-style Hugo theme that gives blogs and documentation the beveled grey chrome of mid-1990s desktop software while carrying an enforced WCAG AA accessibility budget in both light and dark mode.

What is RetroCSS 9x?

RetroCSS 9x is a Hugo theme by PhantomPixelDev that renders blog posts, taxonomies and a documentation tree in the visual language of Windows 95/98 desktop software. You supply Markdown content plus TOML or YAML configuration, and Hugo compiles it into a static site where every surface — buttons, cards, tab strips, modals, code blocks with title bars — is a component from the RetroCSS 6.0.4 UI framework. It covers Hugo 0.158.0 and newer and runs on the standard Hugo binary, because the framework's compiled CSS and JS are vendored rather than built with Sass or Node. The theme adds roughly eighty lines of layout CSS and nothing else.

What makes RetroCSS 9x stand out?

• RetroCSS 6.0.4 foundation — the theme wires the framework's compiled assets into Hugo Pipes with Subresource Integrity fingerprinting, so there is no second palette and no per-page colour overrides.
• Dark mode with no flash — the dark palette ships under both the prefers-color-scheme media query and the data-theme attribute, so a dark-OS visitor is painted dark on the first frame; CI fails the build on a theme flash.
• Enforced WCAG AA — the page gate renders every page of the demo site in Chromium at 1200, 980, 760, 420 and 360px in both themes, failing when any rendered text node falls below AA against the surface actually painted behind it.
• Keyboard gates — skip link, roving tabindex on tab strips and rating groups, tooltips on focus and named controls are asserted by an automated keyboard check, not just claimed.
• No Sass, Node or CDN — the site works offline and under a strict Content Security Policy; the standard Hugo binary is enough.
• Blog and docs in one theme — post grids, pagination, RSS and taxonomies sit alongside a weighted docs tree, breadcrumbs and in-page contents.
• Build-time search index — the index is a page resource generated at compile time and searched entirely in the browser, with no search library.
• Right-to-left support — one config line mirrors the layout; bevels deliberately do not mirror.
• Fifteen-plus shortcodes — alert, card, badge, button, tabs, accordion, modal, toast, progress, rating, carousel, table, avatar and tooltip.
• Optional comments — giscus, utterances or none.

Templates included: home.html, section.html, page.html, taxonomy.html, term.html, docs/section.html, docs/page.html, search.html and 404.html, plus render hooks for figures, external-link marking, heading anchors and code-block title bars with copy buttons.

Who should use RetroCSS 9x?

• Hugo bloggers: publish posts with tags, categories, reading time, author bylines, related posts and pagination at a configurable pager size.
• Technical writers: ship product or project documentation through the type-based docs section with a sidebar tree, breadcrumbs, prev/next and in-page contents ordered by page weight.
• Accessibility-focused developers: adopt a theme whose dark mode, contrast and keyboard behaviour are verified by CI gates rather than asserted in marketing copy.
• Air-gapped or CSP-strict deployments: serve a static site that makes no CDN calls and needs no Node toolchain.

What can you do with RetroCSS 9x?

• Retro-styled blog: build a post feed with a featured post card, tag cloud, archive listings and an author bio block.
• Documentation site: set the docs page type and a cascade on a section so the tree, breadcrumbs and prev/next all read the weight values.
• Blog plus docs on one domain: use the mainSections and docsSection params to decide where each collection lives.
• Arabic or Hebrew sites: mirror the whole layout with a single configuration line.

How does RetroCSS 9x work?

Install via Hugo Modules, a Git submodule, or by copying the repository into a themes directory. Two settings must live in the site's own config because Hugo does not merge a theme's markup configuration: enabling unsafe Goldmark rendering so shortcodes and render hooks emit real markup, and disabling capitalizeListTitles. Docs pages are selected by page type, and a search page is created by setting the page layout. A file at assets/css/custom.css is concatenated last, so it wins without needing important declarations.

Pricing

RetroCSS 9x is free and open source under the MIT license, with no paid tiers.

Pros and cons

• Free MIT license, with no build toolchain beyond Hugo and a standard (non-extended) Hugo binary.
• Accessibility, keyboard behaviour and theme-flash prevention are verified by automated gates.
• Hugo does not merge a theme's markup config into a site's, so two settings must be copied into your own config manually.
• The page and keyboard checks require Chromium installed through Playwright.

FAQ

Is RetroCSS 9x free?

Yes. The theme is released under the MIT license, so it can be used, modified and redistributed, including commercially. The demo site's cover art ships with RetroCSS, and no Microsoft artwork, icon or font is included.

Which Hugo version does RetroCSS 9x require?

Hugo 0.158.0 or newer. The standard build is sufficient; the extended build is not required, because the framework's compiled CSS and JavaScript are vendored into the theme rather than compiled with a Sass pipeline.

Does RetroCSS 9x support dark mode?

Yes. Dark mode follows the operating system through the prefers-color-scheme media query and can also be set with the data-theme attribute. Because both paths are wired in, the dark palette is applied on the first frame and CI fails the build if a theme flash appears.

Does RetroCSS 9x include site search?

Yes. Search builds an index as a page resource at compile time and runs entirely in the browser, so no external search service or JavaScript library is needed. Search is toggleable through the search parameter.

Can RetroCSS 9x be used for documentation instead of a blog?

Yes. Documentation pages are chosen by page type, so you set the type and a cascade on the section once. A section not named docs also needs the docsSection parameter so the sidebar tree, breadcrumbs and prev/next navigation resolve correctly.