Hugo SeoTax Theme

Hugo SeoTax is a blog theme for the Hugo static site generator that pairs fuzzy client-side search with taxonomy filtering to replace per-tag and per-category static pages with a single dynamic search page.

What is Hugo SeoTax?

Hugo SeoTax is an MIT-licensed blog theme for Hugo (version 0.158 or higher, extended edition) built around "Search + Taxonomies." It takes standard Hugo content — Markdown posts with categories, tags, and optional series front matter — and outputs a static blog with a Fuse.js-powered search index generated at build time, advanced taxonomy filters, and a dark mode. It is maintained by minyeamer.

Key Features

• Dynamic search — Fuse.js fuzzy search with instant results on one search page instead of hundreds of static per-tag/per-category pages; supports keyword, parent category, child category, single tag, and multi-tag queries with AND/OR operators.
• Advanced taxonomy filters — filter by category, tag, or a combination without entering a keyword.
• Configurable list sorting — params.posts.sort and params.search.sort accept newest, oldest, relevance, or disabled; a post-list page type provides static archive routes.
• 27-language client-side i18n — all languages served from a single HTML page; the switcher translates UI text, dates, and ARIA labels without page reload or URL change.
• Dark mode — auto-detects system preference, toggled with Cmd/Ctrl + Shift + S, persisted in localStorage, and synchronized with Disqus comments.
• Mac-style code blocks — highlight.js syntax highlighting, line numbers excluded from copy, one-click copy, and a language label chip (Xcode colors in light theme, VS2015 in dark).
• Shortcodes — bookmark link cards from Open Graph metadata, CSV data tables, an image shortcode with click-to-zoom and CLS prevention, series navigation, plus Hugo Book components (columns, hint, mermaid, katex, tabs, details).
• PWA and performance — Service Worker precache support, a 26-icon IcoMoon subset font (~40 KB vs 800+ KB Font Awesome), Schema.org structured data, and reported CLS of 0.002 with 0 ms TBT.

Who is it for?

• Technical bloggers who write in several languages and want UI translation without duplicating pages per language.
• Writers with deep tag and category taxonomies who need readers to narrow a large archive by combining filters.
• Hugo users migrating from heavier themes who want a PWA-ready blog with SEO structured data and low layout shift.

What can you do with Hugo SeoTax?

• Multi-language publishers: enable client-side UI translation across 27 languages while keeping search indexes scoped per content language so results don't mix.
• Series writers: group posts sharing a series front matter value into Velog-style navigation with a collapsible post list and prev/next links.
• Documentation-style bloggers: embed Mermaid diagrams, KaTeX equations, tabbed panels, and CSV tables directly in Markdown posts.

How does Hugo SeoTax work?

Install as a Git submodule or Hugo module, set theme: "seotax", and configure a single config.yaml. Set disableKinds: ["term"] to serve one dynamic search page instead of per-tag static pages. Post front matter uses a two-level category hierarchy: the first categories entry is the parent, the second the child.

Pros and cons

• Pros: single search page eliminates static taxonomy page bloat; no per-language page duplication; extensive shortcode set.
• Cons: requires Hugo 0.158 or higher (extended); optimal image handling requires storing local copies under assets/_images/ for dimension extraction.

FAQ

Is Hugo SeoTax free?

Yes. The theme is released under the MIT license, so you can use and modify it freely, including in commercial projects.

Does Hugo SeoTax support Disqus and Giscus comments?

Yes. params.comments.provider accepts either giscus or disqus; Disqus shortname or Giscus repo, repoId, category, categoryId, and mapping are set in params.comments.

What Hugo version does Hugo SeoTax need?

Hugo 0.158 or higher, extended version, is required. Installation guides cover Git submodule, Hugo module, and from-scratch setups.