hugo-theme-introduction: a minimal Hugo theme that grows into a site

One theme, two shapes

Introduction is described as a minimalist, highly versatile theme for Hugo, and the versatility comes from a single decision: it can be configured as a single page or as a full-featured site with multiple sections.

That is not a cosmetic difference. A single page site is one index file with some sections, and it is what most personal sites need. A full site adds the projects section and the blog section, with their own index files, their own ordering and their own templates. The theme ships both, and which one you get is a matter of what you put in your content directory.

The rest of the surface is short. It is multilingual, with support for side-by-side content in different language versions, and it is responsive with a light and a dark theme. The index page is assembled from Markdown files rather than from a template, so the sections of the home page are content, not configuration.

The design details are the ones a reader notices. There is a page load fade-in effect and smooth scrolling to anchor links, the Markdown is styled throughout including post titles, and there is syntax highlighting for code blocks. The readme points new users to the Hugo fundamentals documentation, which is a sensible thing for a theme to do for the people who will install it.

The theme is Apache 2.0 licensed, its primary language is HTML, and the release history shows recent work: version 6.0.2 and 6.0.3 on 2026-06-20 and 6.1.0 on 2026-09-08, described as Hugo modernisation and interaction fixes, with the last push to the repository on 2026-10-16.

The home page is a directory of Markdown files

The content model is where most of the theme's flexibility comes from, and it is explained in enough detail in the readme to be followed without guessing.

The home page content lives under content/home/, and each Markdown file in that directory becomes a section on the home page. The ordering is a weight value in the frontmatter, and an image can be set to appear on the left of a section, with the image file placed in the same folder. A contact.md file is special, because it is always shown as the last section.

Above that sits the introduction itself, created with the Hugo new command:

hugo new home/index.md

The title frontmatter becomes the first large heading and the content of the file becomes a subtitle line, and the readme mentions the headless option in the frontmatter with a link to the documentation on headless bundles for anyone who wants the section without a page of its own.

The projects section works the same way, with an index file, and each project is a directory holding an index file and its images. More than one image produces a carousel gallery, the images are ordered by filename, and the first one is the preview image unless you override it with a weight in the resource parameters. A project can also link out to another site with the external_link parameter, and an arbitrary string such as a project timeframe can be shown on the home page and in the modal.

The blog is a third section, with its own index file and one file per post. Every section ends up on the home page, so the home page is a summary of the site rather than a separate page.

Hugo extended, Node and a PostCSS step that only production builds get

The requirements are specific, and there is a difference between the preview and the real build that anyone deploying this needs to understand.

The theme requires Hugo extended 0.163.0 or later, and the readme notes that the minimum supported version and the latest release are both tested in continuous integration. Production builds additionally require Node.js 22.12 or later and the theme's local PostCSS dependencies, which you install from the theme directory with the locked versions:

npm ci --ignore-scripts

And when the theme is used inside another Hugo site, the theme's local tools have to be on the path before the build:

PATH="$PWD/themes/introduction/node_modules/.bin:$PATH" hugo

The reason for that is stated in the next paragraph, and it is the important detail. hugo server previews compile Sass without PostCSS, while production builds use PostCSS to add browser prefixes. No global npm packages are required, which is the point of the path juggling, but it does mean the preview is not the same output as the build.

So a theme that looks right in development can look different in production for exactly one class of reason, the vendor prefixes, and the readme is honest that this is the case rather than papering over it. The Sass side is handled by Hugo Pipes, which compiles the stylesheets as part of the Hugo build, and the use of Sass variables is what makes a new colour scheme a matter of setting a few values.

The demo pins its own Hugo version, and the pin has to be moved by hand

The Netlify demo is a fully automated build of the example site, and the readme explains its mechanics in the detail of someone who has been bitten by them.

The live demo automatically builds and publishes successful pushes to the master branch, and the netlify.toml file controls the build. It runs npm run build and npm run check:html from the repository root and publishes the docs directory.

The pin is the interesting part. The demo pins Hugo 0.165.0 and Node.js 24, which is separate from the theme's minimum supported Hugo version of 0.163.0. New Hugo releases are tested by continuous integration, but the demo's pin has to be updated explicitly, which means the demo can be running an older Hugo than the one the theme supports and nobody finds out from the test run.

The readme also says that settings in netlify.toml take precedence over matching settings in the Netlify dashboard, which is worth knowing because it is the opposite of the assumption many people make about the relationship between a configuration file and a hosted service's own settings.

And the operational advice after deploying is concrete. Verify the Hugo version in the production build log, check that the images load from the demo domain, and be aware that a failed build leaves the previous successful deployment live, so a broken push does not take the site down but also does not raise an alarm on its own.

Regression tests in Python and in Node

Most themes have no tests at all, and this one has two suites and a link checker, so it is worth spelling out what they cover.

The test script runs a Python unit test discovery over the tests directory and then a Node test file, both in verbose mode:

"test": "python3 -m unittest discover -s tests -v && node --test tests/browser.test.cjs"

The Python part needs Python 3.9 or newer and the Node part needs Google Chrome, which tells you that the browser tests are real browser tests, driven by playwright-core, which is in the development dependencies alongside autoprefixer, postcss and postcss-cli.

The link checker is a separate script, run after the build, and it takes the base URL of the built site and a list of hosts to forbid:

"check:html": "python3 scripts/check_html.py docs --base-url https://hugo-introduction.netlify.app/ --forbid-host example.com"

The forbidden host is the interesting parameter. The example site is full of placeholder links, and a build that accidentally leaves an example.com URL in a page is a common failure that a human reviewer will not catch on a screenshot. Checking for it automatically is the kind of detail that a theme used in production starts needing.

The readme also notes that the tests use temporary copies and leave the local content and the generated resources untouched, which is what lets you run them on a working tree without committing the noise.

Modernisation is real but partial

The version 6.1.0 release is described as Hugo modernisation and interaction fixes, and the readme is candid about how far that modernisation goes.

Navigation and the project dialogs now use native JavaScript, and the existing Owl Carousel still uses bundled jQuery. So the theme has moved part of its way off a library dependency and not all of it, and the carousel is the part that still needs jQuery in the bundle.

For a Hugo theme that is worth noticing, because Hugo's own asset pipeline can bundle a jQuery copy for a single component, and a theme that removes that needs either a rewrite of the component or a change of carousel.

The repository layout matches the rest of the story. There are layouts for the templates, assets for the Sass and the images, static for files served as they are, i18n for the translations, archetypes for the content templates, an exampleSite directory with a fully configured site, scripts with the build and check helpers, and tests with the two suites. The theme.toml file is what makes it installable as a Hugo module, and the .npmrc file pins the npm behaviour for the build.

The last push to the repository was on 2026-10-16, so the theme is being maintained, and the readme points at the Hugo installation instructions for anyone whose Hugo is too old to run it.

Editorial conclusion

hugo-theme-introduction fits a person or a small studio who wants a personal site with sections, a projects gallery and a blog, and who does not want to maintain a front end stack to get there, because the content model is plain Markdown with frontmatter weights and the build is one Hugo command plus a PostCSS step. It is the wrong choice if you want a theme with a plugin ecosystem behind it, since this one is deliberately small and asks you to write your own templates when you need something specific, and it is the wrong choice if you cannot install Node, because the production build adds browser prefixes with PostCSS and the development preview does not. Before you deploy, run the build and the link checker the way the readme describes, and copy the configuration from the example site rather than writing your own from scratch, since the theme's sections, orderings and colour schemes all hang off that file.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. victoriadrake/hugo-theme-introduction on GitHub