Hugo Theme Luna is a performance-first, SEO-friendly Hugo theme that turns Markdown content into a fast static website with built-in dark mode, PWA support, local search, and image galleries. Created by Ice-Hazymoon, this open-source theme (GPL V3.0) requires hugo-extended 0.146.0 or newer, Node.js 20 or newer, and PostCSS CLI.
What is Hugo Theme Luna?
Hugo Theme Luna is a static site theme for the Hugo generator, designed for speed and search-engine visibility. It accepts standard Hugo content (Markdown, front matter, and images) and outputs a complete blog or documentation site. The theme earns its "performance-first" label by using Tailwind CSS for utility-first styling, lazy loading for images, Pjax navigation via swup.js, and Hugo's built-in image processing to crop and resize images automatically. It also includes an optional article encryption feature, though the documentation explicitly warns not to encrypt important content.
Key Features
- Tailwind CSS - The theme is built on Tailwind CSS, with custom SCSS files for additional styling.
- Dark mode - A built-in toggle that respects user system preferences.
- PWA support - Makes the site installable and usable offline.
- Local search with FlexSearch - Client-side search that reduces index size by excluding shortcodes and code blocks.
- Article encryption - A hugo-encrypt script protects content with a password, but the docs advise against encrypting critical material.
- Multilingual + Google Translate - Supports multiple languages and integrates Google Translate for quick switching.
- LaTeX via KaTeX - Fast math typesetting for technical content.
- Bionic Reading - An optional reading mode that highlights word beginnings for faster scanning.
- Image gallery and carousel shortcodes - Ready-to-use components from the theme's shortcode library.
- Comments via giscus - Integrates GitHub Discussions, with a custom provider partial for alternatives.
Who is it for?
- Personal bloggers who want a fast, modern blog with SEO features and minimal JavaScript overhead.
- Technical writers publishing math-heavy or code-heavy articles, thanks to KaTeX and extensive shortcodes.
- Developers who need a customizable Hugo theme with Tailwind, SCSS, and clear deployment paths to GitHub Pages, Netlify, Vercel, or Cloudflare Pages.
- Multi-language site owners who need built-in translation and Google Translate support.
What can you do with Hugo Theme Luna?
- Launch a personal blog: Copy the exampleSite configuration, add your content, and deploy to GitHub Pages using the included GitHub Actions workflow.
- Build a documentation site: Use the table of contents, local search, and shortcodes to create navigable technical references.
- Run an image-focused blog: Rely on Hugo's image processing and lazy loading to keep page weights low.
How does it work?
The theme is installed as a git submodule, followed by an npm install for dependencies. You copy the hugo.yaml from exampleSite into your site root and build with Hugo. Deployment is automated through GitHub Actions, Netlify, Vercel, or Cloudflare Pages using configuration files provided in the repository.
FAQ
Is Hugo Theme Luna free?
Yes, it is open source under GPL V3.0. You can use it freely, but derivative works must also be GPL-licensed.
What are the system requirements?
Hugo extended version 0.146.0 or greater, Node.js version 20 or greater, and PostCSS CLI installed globally.
Does it support comments?
Yes, it uses giscus (GitHub Discussions-based comments). A custom provider partial allows integration with other systems.
How do I enable article encryption?
Wrap content in the hugo-encrypt shortcode and run hugo-encrypt.js after building. The documentation recommends against encrypting important data.
Can I customize the theme without modifying it?
Yes. Override partials like head.html, footer.html, script.html, and icons.html by placing same-named files in your site's layouts/partials/custom directory, and add custom SCSS or TypeScript through custom.scss and custom.ts.
