hugo-xmin: a Hugo theme kept at 140 lines on purpose

A theme whose selling point is that you can read it

XMin is a Hugo theme written by Yihui Xie in about four hours, and the time is broken down: half an hour on the Hugo templates and 3.5 hours on the styling.

The stated motivation is not to be the best theme but to provide a really minimal example to beginners of Hugo templates. That reframing matters. Most Hugo themes are large because they solve many problems at once, and reading one to understand how Hugo templating works is a poor way to spend an afternoon. A theme that fits on a screen can.

The theme name is a pun on the minimal Hugo theme, and the theme's own motto is that you should keep it simple but not simpler.

The tagline is that it contains about 140 lines of code in total, including the code in the HTML templates and CSS, also counting empty lines. Including empty lines is a stricter standard than you would expect, and it is stated because it makes the number verifiable rather than arguable.

The theme is hosted at xmin.yihui.org, and there is a screenshot of the rendered result in the repository under images/.

The line count is published with the command that produced it

The README does something that few projects do. It shows you exactly how the line count was measured, so you can reproduce it.

find . -not -path '*/exampleSite/*' \( -name '*.html' -o -name '*.css' \) | xargs wc -l

The find invocation skips the exampleSite directory, because the example site is scaffolding rather than the theme itself, and it selects only .html and .css files, so it counts templates and styles and nothing else.

The output follows, and it is the entire theme in nine lines.

      12 ./layouts/single.html
      20 ./layouts/list.html
      13 ./layouts/terms.html
       5 ./layouts/404.html
       0 ./layouts/_partials/foot_custom.html
       0 ./layouts/_partials/head_custom.html
       9 ./layouts/_partials/footer.html
      20 ./layouts/_partials/header.html
      51 ./static/css/style.css
       7 ./static/css/fonts.css
     137 total

Read the shape of it. The largest single file is the stylesheet at 51 lines. The largest template is the header partial at 20 lines, matched by the list template at 20 lines. The single page template is 12 lines and the taxonomy terms template is 13. The 404 template is 5 lines.

The two zero line files are the interesting ones. foot_custom.html and head_custom.html are empty, and their names say what they are for: extension points that the theme author deliberately leaves blank so a site owner can add their own markup without editing the theme files.

Why the CSS stays at 51 lines

The author addresses the obvious objection directly. He says he can certainly further reduce the code, for example by eliminating the CSS, but believes that a tiny bit of CSS can greatly improve readability, and points out that you cannot really find many CSS frameworks that only contain 50 lines of code.

That is the whole argument for the styling, and it is a defensible one. A theme with no styling at all would produce a functional but ugly page, and a theme that pulled in a framework would add hundreds of lines and a dependency, which defeats the purpose. Fifty-one lines of hand written CSS is the point where the output stops looking broken while the file stays short enough to read in one go.

The split between the two stylesheets follows the same logic. The main style.css holds 51 lines of the layout and visual rules, and fonts.css holds 7 lines, which is the kind of file that stays separate because font declarations are a distinct concern and a distinct thing to override.

The honest way to read this theme is as an argument that theme complexity is a choice rather than a requirement. The claims are modest and testable. You can count the lines. You can open each file. And you can decide for yourself whether the missing features matter for your site.

The file tree tells you what the theme covers

The top level entries are short enough to read as a specification of the theme.

The layouts/ directory holds the four templates and the four partials from the count above: single.html, list.html, terms.html and 404.html at the top level, and _partials/ containing foot_custom.html, head_custom.html, footer.html and header.html. The single template is the one for an individual page, the list template is the one for a section, the terms template handles the taxonomy listing, and 404.html handles the not found case.

The static/ directory holds the CSS.

The archetypes/ directory is the Hugo convention for content templates, which is what tells the tooling what to put in a new file when you ask Hugo to create one.

The exampleSite/ directory is a complete example of a site using the theme, which is the standard Hugo way of shipping a theme and it is excluded from the line count precisely because it is scaffolding rather than theme code.

There is a theme.toml file, which is the metadata file Hugo themes carry, and a hugo-xmin.Rproj file, which is an RStudio project file, a small sign that the theme doubles as a teaching artefact for people coming from another toolchain.

The images/ directory holds the screenshot. And there is a LICENSE.md file and a README.md at the root, plus a .gitignore and a .github directory.

What is missing, and why that is the point

The absence of features is the design.

There is no navigation menu partial in that file list. There is no comment system integration, no search, no tag cloud beyond the taxonomy template, no pagination control, no breadcrumbs, no analytics snippet, no dark mode toggle, no contact form. The footer is 9 lines and the header is 20.

For a site that needs those, this theme is the wrong starting point and you would end up writing them. For a site that needs a single page, a small blog, or a documentation site where the reader navigates by URL, it is sufficient as it stands.

The two empty custom partials are the escape hatch for the most common need. The head one is where you would add a stylesheet of your own, a verification meta tag, or a font. The foot one is where you would add a script, an analytics snippet, or a footer note. Because they are separate files, you add to them without touching the theme's own templates, which means your changes survive a theme update.

That is a small design decision with real consequences, and it is the kind of thing you only notice when you have read the whole theme, which is precisely the argument for the theme existing.

Licence, maintenance state and who this is for

The licence is MIT, recorded in the LICENSE.md file at the repository root.

On maintenance, the repository is not archived and the last push was on 2026-06-08. It publishes no GitHub releases, so there is no tagged version to pin and no release note to read. The README itself carries no changelog, no support statement and no roadmap.

That combination of facts tells you what this is. A theme with no release process and no recent churn is not a theme that is being actively maintained as a product. It is a teaching artefact that happens to also be a working theme, and the author says as much by giving the motivation as providing a minimal example for beginners of Hugo templates.

For the intended reader the value is concrete. You can read the entire theme, understand how a Hugo theme is laid out, how partials are pulled into templates, where the extension points are, and how a minimal stylesheet achieves a readable result. Then you copy it and grow it into whatever you need.

For a team that just wants a fast, plain blog with no dependencies, it is also a perfectly serviceable choice, since minimal is not a compromise here, it is the requirement.

Editorial conclusion

Adopt hugo-xmin if you want to read a complete Hugo theme end to end in one sitting, since 137 lines across four templates, four partials and two stylesheets is small enough to understand before copying anything. Do not adopt it as a production site theme if you need a navigation menu, comments, search, pagination controls or a dark mode, because none of those are in the file inventory. Verify first that the Hugo version you use still matches the template conventions in the layouts directory, that the exampleSite/ directory gives you a working starting point, and that the theme.toml file matches the Hugo version you target, since the repository publishes no release tags and the last push was on 2026-06-08.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. yihui/hugo-xmin on GitHub