panr/hugo-theme-terminal: a monospace Hugo theme for terminal-flavoured sites

The problem Terminal solves: a blog that looks like the tools you write about

Most Hugo themes are designed for a magazine, a product page or a portfolio. Terminal is designed for the opposite case: a personal site where the writing is the point and the visual language is a monospaced terminal. The README describes it as a simple, retro theme, and the topic list on the repository includes monospace, duotone, firacode and minimal. That is the whole brief.

The audience is narrow and identifiable. Someone who writes about Linux, Go, CSS or self-hosted software and wants the site to read like the editor they are typing in. Someone who has already picked Hugo and does not want to fight a JavaScript build pipeline to get a header and a post list. The repository is CSS-first, with a small amount of JavaScript tooling in package.json for linting (eslint, stylelint, husky) rather than for rendering the site.

If you want a landing page with a hero image, three feature cards and a pricing table, this is the wrong theme. It gives you an index, posts, shortcodes and a menu. That is roughly it.

How the theme is put together: Hugo Pipes, Modules and Chroma

The README states the theme is fully based on the Hugo ecosystem, specifically Pipes and Modules. That is a design commitment with consequences. Assets are processed by Hugo rather than by a separate bundler, so there is no webpack or Vite step in the build; the Node dependencies in package.json exist for linting and for husky git hooks, not for producing the final CSS.

Code highlighting comes from Chroma, Hugo's built-in highlighter. The theme ships a custom duotone style on top of it, and the config the README provides sets markup.highlight.noClasses = false. That setting matters: it makes Chroma emit CSS classes instead of inline styles, which is what lets the theme's stylesheet colour the tokens. Flip it and the highlighting will not look like the demo.

Colour schemes are not hardcoded. The README points to Terminal.css, a separate generator at panr.github.io/terminal-css/, for producing a scheme. Fira Code is the default monospaced font. The layout tree (layouts/, assets/, static/, archetypes/) follows the standard Hugo convention, so anyone who has edited a Hugo theme before will recognise where to look.

The shortcodes are the most opinionated part. image takes a required src plus optional alt, position (left is the default, with center and right available) and style. code takes a required language plus optional title and open. The README's example for code shows a CSS snippet wrapped in the shortcode with open="true", which renders the block expanded rather than collapsed.

Installing Terminal: three routes and one hard requirement

The README is explicit that the theme needs at least Hugo Extended v0.90.x. Extended is the build with SCSS support compiled in. Check that before anything else, because a standard Hugo binary will not build the theme's stylesheets.

There are three documented installation routes: as a Hugo Module, as a local clone into themes/terminal, or as a git submodule. The module route is the one the README treats as primary. If this is your first Hugo Module, initialise your own module first, then fetch the theme:

hugo mod init github.com/yourname/yoursite
hugo mod get github.com/panr/hugo-theme-terminal/v4

Then add the import to your configuration file. The README shows this block, including a commented-out replacements line for the submodule case:

[module]
  # replacements = "github.com/panr/hugo-theme-terminal/4 -> themes/terminal"
[[module.imports]]
  path = 'github.com/panr/hugo-theme-terminal/v4'

The README notes a consequence people miss: with the module route the theme does not appear in your themes directory, and go.sum pins the version you fetched. If you prefer a visible directory, clone instead:

git clone https://github.com/panr/hugo-theme-terminal.git themes/terminal

Or add it as a submodule:

git submodule add -f https://github.com/panr/hugo-theme-terminal.git themes/terminal

The README documents one specific failure and its fix. If Hugo reports module "terminal" not found; either add it as a Hugo Module or store it in "[...your custom path]/themes"., and you are using the module route, remove theme = "terminal" from your config file. That line is only for the directory-based installs.

To run the site, the README gives one command:

hugo server -t terminal

The README says the site is then at localhost:1313 and that changes go live without a manual refresh. The -t terminal flag is what selects the theme when it is not set in config.

A first real configuration pass

The README says the theme does not require advanced configuration, and provides a config block to copy. The parts that change behaviour immediately are the params. contentTypeName defaults to posts and controls which content directory feeds the index page. showMenuItems defaults to 2 and, per the README, setting it to 0 leaves only the submenu trigger visible. autoCover, when true, picks up a cover.jpg, cover.png or cover.webp from the resource directory without a front-matter field.

A trimmed starting point, using the keys the README documents:

baseurl = "/"
languageCode = "en-us"
theme = "terminal"
pagination.pagerSize = 5

[markup.highlight]
  noClasses = false

[params]
  contentTypeName = "posts"
  showMenuItems = 2
  autoCover = true
  showLastUpdated = false

If you use git and want the last-updated line to be automatic, the README says to set enableGitInfo to true and then showLastUpdated to true. The date format is controlled by dateFormat, documented as defaulting to "2006-01-02", and the README warns that a wrong server timezone will render dates differently than expected. That is a Go time layout string, not a strftime pattern, and the README links to the Hugo time.Format documentation for the full set of tokens.

There is a limit worth flagging. The README's config block is truncated in the repository copy, ending mid-comment inside the dateFormat example. If you are looking for a complete annotated reference, the README is not it; you will be reading layouts/ and assets/ to find the rest.

Where Terminal is the wrong tool

The theme has no search, no taxonomy widgets beyond what Hugo gives you, no comment system and no analytics integration documented in the README. Those are not defects in a minimal theme, but they are real gaps if your site is meant to be a hub rather than a notebook.

The harder constraint is the toolchain. Requiring Hugo Extended v0.90.x rules out environments where you only have the standard binary, and the module route adds a Go toolchain and a go.sum file to your repository. That is more moving parts than dropping a folder into themes/. The README's own troubleshooting entry, the module "terminal" not found error, is a symptom of how easy it is to mix the module route with the directory-route config key.

There is also a visual ceiling. A duotone monospace theme reads well for prose and code and badly for photography, product shots or anything that needs a wide palette. If your content is image-led, the theme is fighting you. The README says nothing about rollback or migration between the three install methods, so switching from a submodule to a module later is your problem, not a documented path.

Terminal against a general-purpose Hugo theme

The obvious comparison is with a general-purpose theme such as Stack, which appears in the searches people run around this project. The difference is not quality, it is the shape of the output. A theme like Stack is built to host a mixed site: cards, sidebar widgets, multiple content types, a search box. Terminal is built to render a list of posts and the posts themselves in one typeface and two colours.

That means Terminal gives you less to configure and less to break, and it also means you will write your own partials the moment you want anything Stack ships by default. The trade is explicit. If you want the site to look like a terminal, Terminal gets you there with a config block and a colour scheme from Terminal.css. If you want a site that can absorb a portfolio page, a docs section and a blog without custom layout work, a broader theme will cost you less time.

The other distinction is the styling pipeline. Terminal leans on Hugo Pipes and Chroma, so the CSS is processed inside the Hugo build. Themes that ship a prebuilt stylesheet and a separate asset pipeline behave differently when you want to change a colour: here, the README directs you to the Terminal.css generator rather than to a Sass variable file.

Maintenance, licensing and what it costs to keep running

The repository is not archived. The last push was on 2026-09-21, and the most recent release in the list is v4.2.6 on the same date, following v4.2.5 and v4.2.4 in August 2026. On the evidence of the release list, the project is being tagged regularly, with patch releases rather than major version jumps. The module path carries a v4 suffix, so a future v5 would be a breaking import change for anyone on the module route.

Upgrade cost depends on your install method. With the module route, go.sum pins the exact revision, so upgrading is an explicit hugo mod get against the module path and a commit of the changed go.sum. With a submodule, it is a git submodule update. With a plain clone into themes/terminal, there is no version pinning at all and you are tracking master. The README does not describe a migration path between these methods, so pick one deliberately at the start.

The licence is MIT, stated in the repository and in package.json. MIT permits reuse and modification with the copyright notice retained; it does not cover the third-party assets the theme references, such as the Fira Code font, which is a separate project with its own licence. That is a general point about bundled fonts, not legal advice about your situation. If you redistribute the theme, check each referenced asset's own terms.

Editorial conclusion

Adopt Terminal if your site is mostly prose, code and links, and you are willing to run Hugo Extended and edit config.toml by hand. Skip it if you want a page-builder feel, a portfolio grid, or a theme that ships its own admin UI; the repository has none of those. Before committing, verify your Hugo build reports Extended, run hugo server -t terminal against the exampleSite, and check that markup.highlight.noClasses = false is set, because the duotone code blocks depend on it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. panr/hugo-theme-terminal on GitHub
4. README
5. Releases