hugo-theme-console: a terminal styled Hugo theme built on CSS variables

Two ways to install the theme, and they lead to different update paths

The theme can be added to a Hugo site in either of the two ways Hugo supports, and the choice is not cosmetic because it determines how you receive updates.

As a git submodule, you clone it into themes/hugo-theme-console from the root of your site:

$ git submodule add https://github.com/mrmierzejewski/hugo-theme-console.git themes/hugo-theme-console

As a Hugo module, you first turn the site itself into a module, then declare the theme as a dependency:

$ hugo mod init github.com/my-username/my-new-site

$ hugo mod get github.com/mrmierzejewski/hugo-theme-console

The module route then needs a matching import block in your hugo.toml:

[[module.imports]]
  path = "github.com/mrmierzejewski/hugo-theme-console"

The submodule approach vendors the theme into your repository history, so theme updates arrive as a submodule pointer change you control. The module approach records the dependency in go.mod, and the repository does include a go.mod file declaring module github.com/mrmierzejewski/hugo-theme-console against go 1.12. Either way the theme itself is set with a single line in your configuration:

theme = "hugo-theme-console"

Note the difference in names between the two paths. The submodule directory and the theme setting use hugo-theme-console, while the module import path uses the full github.com/mrmierzejewski/hugo-theme-console. Mixing those up is the most likely first-hour mistake here.

The visual language comes from Terminal CSS, not from custom templates

Console is described as inspired by the system console, and the styling underneath is based on the Terminal CSS framework, a modern and minimal one. That distinction matters for maintenance and for expectation setting.

The theme is not drawing its own terminal chrome from scratch. It starts from Terminal CSS and overrides it. The mechanism for that is a set of CSS custom properties, which the theme exposes so you can restyle it without touching the templates. The default set defines the font size, the font color, the monospace stack, the general font stack, the line height, the page width and a flag for the h1 decoration:

:root {
    --global-font-size: 16px;
    --global-font-color: #444;
    --global-line-height: 1.6em;
    --page-width: 70em;
    --display-h1-decoration: 1;
}

Dark and light modes are separate blocks of the same variables, switched through prefers-color-scheme media queries. The dark block sets a background of #222225 and a page width of 60em, narrower than the 70em used in light mode, along with a primary color of #62c4ff and a code background of #3f3f44. The light block inverts those choices, with a white background, a primary color of #1a95e0 and a code background of #e8eff2. A third block at a maximum width of 850px drops the font size to 14px while keeping the page width at 70em.

So the responsive behaviour is partly handled by the variable layer rather than by layout code, which is why the theme can claim support for desktop, tablet and mobile without shipping a separate mobile layout. The tradeoff is that the page width in dark mode differs from light mode, so a long line of code wraps differently between the two, which is a detail that only shows up when you read a lot of code on a wide screen in dark mode.

Overriding the style means adding one file, assets/css/custom.css

Customisation is documented as a single file. You create assets/css/custom.css in your site directory, and because it sits in the assets pipeline, its rules load after the theme defaults and win on equal specificity.

That file needs no registration in the configuration. The variables shown in the previous section are the ones you are expected to copy into it and adjust, and the README's example demonstrates the full set, including the monospace font stack and the general font stack, both of which list a series of fallbacks ending in monospace, serif.

The practical advice here is to change variables rather than write selectors. If you set --primary-color, the accent color in both dark and light mode follows, including the progress bar fill and the link styling, because they are all reading the same custom property. If you instead write a rule for a specific link class, you are fighting the theme on every future update.

The theme also exposes an animation option through the configuration rather than through CSS. The params block carries a description, an animateStyle setting for content animation, and a set of navigation links:

[params]
  description = "Your site description"
  animateStyle = "animate-fade-up" # Animation style for content

Navigation entries are a list of tables rather than a map, so each link needs its own [[params.navlinks]] block with a name and a url. The example site uses About, Posts and Photos, which lines up with the three content types the theme supports.

The exampleSite directory is the real documentation for content layout

The README points new users at the exampleSite folder and describes it as containing an example config file and the content for the demo. There is also a makefile at the top level, and the README gives a single command to run it:

make hugo-server

The example site shows the three content types the theme expects. An about section holds a single index.md. A posts directory holds an introduction folder with its own index.md, which is the folder-per-post convention Hugo uses. A photos directory holds a location-named folder, arizona-us, containing a jpg and an index.md, which is how the gallery is populated: each image lives beside a page that describes it.

The example site also carries its own layouts and static directories, which shows the intended override points. When you want a template changed, you copy the relevant file from the example site's layouts directory into your own site's layouts, and Hugo will use yours in preference to the theme's. The README's instruction for the configuration is blunt about it: copy at least the hugo.toml from the root of the example site into your own site, overwriting the existing config file if necessary.

The repository layout supports that workflow. Alongside the exampleSite directory there is a layouts directory, a static directory, images for the README assets, and theme.toml, which carries the theme metadata Hugo reads when the theme is listed.

Hugo v0.146.0 is a hard floor, and TEMPLATE_UPGRADE.md explains why

The theme declares compatibility with Hugo v0.146.0 and newer, and it has been updated to the new template system, with the details written up in TEMPLATE_UPGRADE.md at the repository root. That file is the one to read before you upgrade a site that already uses this theme.

The requirement is a version floor rather than a soft preference, and the reason is structural: the template system itself changed, so templates written for the old system do not behave the same way. A site pinned to an older Hugo release will not build with this theme, and the fix is to move Hugo forward rather than to look for a compatible theme build, since the repository publishes no GitHub releases and there is no older tagged version to fall back to.

Running the site locally is a two-command affair once the configuration is in place. Hugo's own development server serves the site for you:

hugo serve

The site then appears at http://localhost:1313. For deployment, the production build is:

hugo --minify

The minify flag is the reason to prefer it over a plain build for anything you host, since it strips whitespace from the output, and the README states the result is a public/ directory with the optimized site ready for deployment.

The last push to the repository was on 2026-06-18, and there are no GitHub releases, so version tracking is by commit rather than by tag. A theme that depends on a moving Hugo template system and carries no release tags is a dependency worth pinning in your own build process.

MIT licensing with a licence link that points elsewhere

The README states the theme is released under the MIT License and credits the author with a 2026 copyright for Marcin Mierzejewski. The repository has a LICENSE file at its top level, and the licence identifier recorded for the project is MIT.

One detail deserves a check before you redistribute the theme. The MIT Licence link in the README points to the LICENSE.md file in the panr/hugo-theme-terminal repository rather than to the LICENSE file inside this repository. Both are MIT in name, and the theme does credit the Terminal CSS foundation it builds on, but the authoritative text for this theme is the one in its own LICENSE file. Copy that file alongside any fork or redistribution rather than relying on the linked one.

The MIT grant itself is permissive: no copyleft obligation, no requirement to publish modifications, and the only conditions are retaining the copyright notice and the licence text. That makes the theme easy to vendor, modify and ship inside a larger site, which is a reasonable expectation for a presentation layer, and it also means the theme's own maintenance is entirely on the author.

The theme's live demo is hosted at mrmierzejewski.com/hugo-theme-console, and the README includes a preview image in the images directory. Both are useful references when deciding whether the console aesthetic is what you want, since the feature list alone says little about how a terminal layout reads for long-form blog posts.

Editorial conclusion

hugo-theme-console suits a Hugo site that wants a plain, fast, terminal looking presentation with a built in photo gallery and no JavaScript framework, and it is a good fit for a personal site or a docs-adjacent blog. It does not suit a project that needs a theme with a large design system, a page builder or a maintained upstream framework, and it targets a specific Hugo generation: the theme requires v0.146.0 or newer because of the new template system, so a site pinned to an older Hugo release will not build with it. Before you commit, copy the exampleSite/hugo.toml into your own configuration, check the TEMPLATE_UPGRADE.md notes against the Hugo version your CI runs, and confirm the MIT licence in the LICENSE file, since the README links its MIT text to a different repository's URL.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mrmierzejewski/hugo-theme-console on GitHub
4. README