hugo-trainsh is a Hugo theme that turns static blogs into a retro NES/FC pixel experience while keeping reading content primary. Built by Binbin Shen and available on GitHub, it ships with a Retro mode by default plus Light and Dark modes toggled from the header.
What is hugo-trainsh?
hugo-trainsh is a minimal, content-first theme for Hugo static site generators. It takes Markdown content from your site's post directory (configured via the mainSections parameter, such as ["posts"] or ["blog"]) and renders it as a static site with an 8-bit RPG-inspired pixel aesthetic. The theme is created by Binbin Shen and hosted at github.com/binbinsh/hugo-trainsh, with a live demo at hugo-trainsh.pages.dev.
Key Features
- Retro pixel mode by default — Uses a deep-blue background (#00237C) with white pixel-art dialog borders, Fusion Pixel 12px font, RPG-style gold tags, pixel dashed horizontal rules, hard shadows, and zero border-radius; all without CSS transitions so interactions snap like an 8-bit console.
- Three theme modes — Retro (gamepad icon), Light (sun icon), and Dark (moon icon) cycle via a header toggle, defaulting to Retro.
- Multilingual font variants — Fusion Pixel 12px includes per-language variants for Simplified Chinese, Traditional Chinese, Japanese, and Latin.
- Code block enhancements — Syntax highlighting uses the NES palette, with a copy button and soft-wrap toggle on each code block.
- Diagrams and math — Mermaid diagrams and KaTeX math render inside Markdown content.
- Image lightbox — Figures get captions and are viewable through a PhotoSwipe lightbox.
- Blog archive and tags — A
/blog/page grouped by year (enabled by creatingcontent/blog/_index.md) and/tags/taxonomy pages. - Built-in shortcodes — Includes
{{< toc >}},{{< tags >}}(with optionalsort="freq" limit="20"), and{{< recent-posts limit="5" >}}.
Who is it for?
- Retro gaming bloggers — Publish posts with an authentic NES/Famicom visual identity, down to the pixel font and palette.
- Hugo developers — Get a theme with minimal dependencies that installs via
git submodule addand configures with two lines in your site config (theme = "hugo-trainsh"andmainSections). - Multilingual content creators — Write in Chinese, Japanese, or Latin scripts and the theme renders the appropriate pixel font variant per language.
What can you do with hugo-trainsh?
- Add a retro archive — Create
content/blog/_index.mdto enable a /blog/ page that groups posts by year, with /tags/ pages for topic navigation. - Enhance post pages — Drop in shortcodes like
{{< toc >}}for a table of contents,{{< tags >}}to display tag lists, and{{< recent-posts limit="5" >}}for recent entries. - Render rich content — Use Mermaid for diagrams and KaTeX for math without extra setup.
- Custom search or index — Set the home output to
["HTML", "RSS", "JSON"]in Hugo config to generate a JSON version of the homepage for custom index or search features.
How does hugo-trainsh work?
You install the theme as a Git submodule, then set theme = "hugo-trainsh" in your Hugo config. Set the mainSections parameter to match your content directory (for example, ["posts"] for content/posts/), create content/blog/_index.md if you want the /blog/ archive, and Hugo builds the site with the theme's templates. The Quick Start in the README walks through all steps.
FAQ
Is hugo-trainsh free?
Yes, the theme is open-source and available on GitHub at github.com/binbinsh/hugo-trainsh. You can clone it or add it as a submodule to your Hugo project.
Does hugo-trainsh support dark mode?
It includes three theme modes: Retro (default), Light, and Dark. A header toggle cycles between them with a gamepad, sun, and moon icon respectively.
Which languages does the pixel font support?
The Fusion Pixel 12px font has per-language variants for Simplified Chinese, Traditional Chinese, Japanese, and Latin, so multilingual sites render with matching pixel styling.
How do I enable the /blog/ archive?
Create a file at content/blog/_index.md. The theme's /blog/ page then appears with posts grouped by year.
