Hugo Simple is a minimal, no-JavaScript Hugo theme built on Simple.css and Bear Blog that turns Markdown content into fast, SEO-friendly static blog pages. It is open source, maintained by GitHub user maolonglong, and requires Hugo version 0.146.0 or newer to run.
What is Hugo Simple?
Hugo Simple is an open-source Hugo theme that takes Markdown content and produces a static blog with a clean, minimal design. It uses Simple.css for baseline styling and Bear Blog for its typographic and layout conventions. The theme expects a standard Hugo site structure (content in Markdown, configuration via Hugo's config files) and outputs static HTML with no client-side JavaScript. It is hosted at github.com/maolonglong/hugo-simple and can be installed via git submodule or Hugo Modules.
Key Features
- No-JavaScript — The theme ships zero client-side JavaScript, so pages render instantly, work without a JS runtime, and are inherently lightweight.
- Table of Contents — Automatically generates a linked table of contents from Markdown headings, improving navigation on long posts.
- Dark mode — Provides built-in dark and light appearance switching using pure CSS, with no JavaScript required.
- SEO-friendly — Includes per-page metadata defaults that help search engines index content, leveraging Hugo's built-in SEO functions.
- Code highlighting — Syntax highlighting is based on the catppuccin color palette, applied via CSS so it remains JavaScript-free.
- Customization hooks — Offers three override points: custom_head.html, custom_body.html, and custom_footer.html partials where you can inject your own markup, analytics, or styles.
- Notice shortcode — The theme includes a notice shortcode that renders Simple.css-style callout boxes and accepts Markdown inside the notice body.
- Lean and stable — The project is in maintenance mode and considered feature-complete, keeping the core intentionally small rather than accumulating features.
Who is it for?
- Minimalist bloggers — Individuals who want a distraction-free reading experience without complex UI elements or script-heavy interactions.
- Hugo users — Developers already using Hugo who want a small, maintained theme to establish a personal blog or content site quickly.
- Performance-focused site owners — Anyone who prioritizes fast page loads and no-JavaScript behavior, such as accessibility-minded sites or those targeting low-power devices.
- Customizers — Users who want a lean base theme to modify locally through Hugo's layout precedence or by forking the repository for full control.
What can you do with Hugo Simple?
- Personal bloggers: Write Markdown posts in a Hugo content folder and publish a clean, mobile-friendly blog with automatic table of contents, dark mode, and readable code blocks.
- Technical writers: Publish documentation or long-form technical notes where syntax-highlighted code and a clear TOC improve readability.
- Quick prototyping: Use the quickstart template (github.com/maolonglong/hugo-simple-starter) to spin up a new site in minutes without configuring a theme from scratch.
- Developers customizing themes: Add custom partials to inject analytics, extra meta tags, or custom CSS while keeping the core theme untouched.
How does Hugo Simple work?
Hugo Simple works like a standard Hugo theme: you write Markdown content under the content directory, set the theme in your Hugo configuration, and run the Hugo build command to generate static HTML. The installation path is either adding the repository as a git submodule (git submodule add https://github.com/maolonglong/hugo-simple.git themes/hugo-simple) or pulling it via Hugo Modules. Once active, the theme's templates render pages, and shortcodes such as the notice box are available in your Markdown.
Alternatives
- janraasch/hugo-bearblog — A Bear Blog-inspired Hugo theme that Hugo Simple credits as an inspiration and shares a similar minimalist direction.
- clente/hugo-bearcub — Another Hugo theme listed as an inspiration, offering a similar Bear Blog aesthetic.
FAQ
Is Hugo Simple free?
Yes, Hugo Simple is open source and free to use. It is published on GitHub under the maolonglong/hugo-simple repository, and you can install, modify, and fork it according to standard open-source practice.
What Hugo version does Hugo Simple require?
The theme requires Hugo version 0.146.0 or newer. If you run an older Hugo version, the theme may not render correctly, so upgrading to a recent release is recommended.
Does Hugo Simple use JavaScript?
No. The theme is deliberately no-JavaScript, which keeps pages lightweight and ensures all content remains readable even when JavaScript is disabled. Interactive elements like dark mode switching are handled with CSS only.
Is Hugo Simple still being developed?
The theme is stable and in maintenance mode. Its author has stated that no new features are planned because the core is considered feature-complete. Extensibility is provided through custom partials, layout overrides, and the option to fork the theme.
Can I add my own analytics or scripts?
Yes. The theme provides custom_head.html, custom_body.html, and custom_footer.html partials that you can copy into your own layouts directory and edit to inject analytics snippets, meta tags, or additional CSS without modifying the theme's core files.
