Hugo Primer Blog

Hugo Primer Blog is an open-source Hugo theme for building clean, responsive blogs on GitHub's Primer CSS design system, maintained by Atsushi Nagase and released under the MIT License.

What is Hugo Primer Blog?

Hugo Primer Blog is a theme for the Hugo static site generator that converts Markdown content into a blog with an optional sidebar, dark mode, multilingual support, and GitHub-style typography. It supports Hugo v0.146.0 or later (Extended not required) and can be installed as a Hugo Module from the vanity import path go.ngs.io/hugo-primer-blog or as a Git submodule from the GitHub repository ngs/hugo-primer-blog. The theme outputs a fully static site, and with the optional LLMS and Markdown output formats it also produces a llms.txt index and raw Markdown versions of every page for LLM consumption.

Key Features

• Dark mode — automatically detects the system preference, offers a manual override that is saved to localStorage, and lets you set the default to auto, light, or dark via the defaultTheme parameter.
• Multilingual i18n — English and Japanese translations are included out of the box; you define additional languages in hugo.toml with per-language content directories, and one llms.txt is generated per language.
• Primer CSS — the whole UI is built on GitHub's Primer design system, giving links, buttons, and typography a familiar GitHub look; styles are processed with Hugo Pipes.
• Customizable primary color — set params.primaryColor to override the default GitHub blue #0969da; the theme generates appropriate light and dark shades automatically.
• Responsive layout with sidebar modules — enable the sidebar with params.sidebar and compose it from ordered modules for recent posts, tags, categories, archive, links, or your own custom partials.
• LLM-friendly output — the theme ships LLMS and Markdown output format definitions and templates; you opt in per site with the home = ["HTML", "RSS", "LLMS"] and page = ["HTML", "Markdown"] output lists.
• Custom Open Graph tags — per-page ogp front matter recursively becomes meta tags (e.g. profile:first_name), arrays produce repeated properties, and defaults for og:* are auto-generated unless overridden.

Who is it for?

Hugo Primer Blog suits anyone who wants a GitHub-styled blog with minimal setup. That includes:

• Hugo bloggers who want a clean default look without hand-rolling CSS and who need tags, categories, reading time, author display, and share buttons.
• Multilingual site editors who publish in English and Japanese (or other locales) and want per-language content folders, menus, and llms.txt indexes.
• AI-first content publishers who want their posts exposed as raw Markdown and a machine-readable site index for retrieval.

What can you do with it?

• Personal developers: run a tech blog with an archive sidebar, social links, and Google Analytics 4 integration via googleAnalyticsID.
• Project maintainers: use the optional About page and posts section to document a project, with featured images and custom OGP tags for richer link previews.
• LLM tooling builders: enable the LLMS and Markdown outputs to feed a blog's content into AI agents or retrieval pipelines without scraping HTML.

How does it work?

Install the theme as a Hugo module or submodule, then add your content as Markdown files in a content/en/posts/ (or content/ja/posts/) directory. Front matter fields like title, date, tags, categories, author, description, and image control how each post renders. Run hugo and the theme generates a static site; if you enabled the extra output formats, it also writes llms.txt and per-page index.md files into the public/ directory.

Pros and cons

• Pro: No Node.js build step for site owners — Hugo Pipes compiles the Primer CSS assets during the Hugo build.
• Pro: MIT licensed, so you can freely modify and reuse the theme.
• Con: The LLM-friendly output formats are not enabled by default and require a manual outputs block in your site config, because Hugo does not inherit the outputs key from themes.

Pricing

Free — the theme is released under the MIT License, which permits commercial use, modification, and redistribution.

FAQ

Is Hugo Primer Blog free?

Yes. The theme is open source under the MIT License, so you can use it for personal or commercial projects without paying a license fee, as long as you preserve the copyright notice.

Does Hugo Primer Blog require the Extended version of Hugo?

No. The theme works with Hugo v0.146.0 or later, and the standard (non-Extended) build is sufficient because all asset processing is handled by Hugo Pipes, which is built into Hugo.

How do I enable dark mode?

Dark mode is automatic by default: the theme detects the visitor's system preference. You can override it per visitor with a manual toggle on the site, or set the default theme in your config with params.defaultTheme to "auto", "light", or "dark".

How do I enable the llms.txt output?

Add an outputs block to your site's hugo.toml with home = ["HTML", "RSS", "LLMS"]. The theme already defines the LLMS output format and its template, so no other configuration is needed; multilingual sites get one llms.txt per language.

Can I customize the accent color?

Yes. Set params.primaryColor to any hex color, for example "#8250df" for purple. The default is GitHub's blue #0969da, and the theme derives matching shades for light and dark modes automatically.