Hugo Minimalist SPA is a Hugo theme that converts a static Hugo site into a single-page application with AJAX navigation, aimed at minimalist, responsive personal or business websites.
What is Hugo Minimalist SPA?
Hugo Minimalist SPA is a Hugo theme that transforms a multi-page static site into a single-page application. Instead of loading a new HTML page for each link, it fetches Markdown content via AJAX (using jQuery) and swaps it in place, giving the feel of a native app while remaining a static site. The theme takes Markdown files placed in the content folder as input and produces a single index.html with dynamically loaded content, running on the Hugo static site generator. It was created by SAGGameDeveloper (sag-dev) and is distributed under the MIT License.
Key Features
- SPA architecture — All content is loaded into one page via jQuery AJAX requests; no full page reloads when navigating between sections.
- Responsive minimalist design — Focus on simplicity and elegance; works on various screen sizes.
- Markdown-based content — Add or edit pages by creating .md files in the content folder; no database or CMS required.
- Customizable colors — Set header, navbar, link, and heading colors via a theme_style.toml data file; values are passed into SASS.
- Social media integration — Configure social icons by adding a social-media.toml data file; icons are automatically sorted alphabetically (prefix names with numbers to control order).
- Custom fonts and logo — Drop default.otf, default-light.otf, and default-bold.otf into static/fonts to replace the default Less Sans font; place logo.png in static/images to change the logo.
- SASS-based theming — The theme is built entirely with SASS; source files are in assets/sass/ and can be modified to deeply customize the look.
- Custom imports — Inject your own HTML into the page by creating a custom_imports.html partial in layouts/partials/.
Who is it for?
- Personal website owners — Want a one-page site with smooth navigation and a clean aesthetic; they can manage all content from plain Markdown files.
- Portfolio users — Designers, developers, or photographers who need a minimalist, responsive showcase that loads content dynamically.
- Small business owners — For example, a cafe can present menus, about, and contact sections on a single page; the author's example site is a cafe website built with this theme.
- Hugo developers exploring SPA — Users comfortable with Hugo who want to experiment with single-page patterns; the theme's JavaScript core is documented in the README for advanced modification.
What can you do with Hugo Minimalist SPA?
- Create a one-page portfolio: Add project Markdown files and the navbar will list them; each section loads without page refresh.
- Build a small business landing page: Use sections for services, about, and contact, all on one page with a persistent header and social links.
- Publish a personal blog with SPA navigation: Though designed as a one-pager, multiple Markdown files can be ordered and displayed as navigable sections.
How does Hugo Minimalist SPA work?
After cloning the repository into your Hugo site's themes folder and setting theme = "hugo-minimalist-spa" in config.toml, you place .md files in the content folder. The theme builds an index.html where the navbar lists your content alphabetically (or via custom titles set in front matter). When a user clicks a navbar link, JavaScript sends an AJAX request to fetch the corresponding Markdown-rendered HTML snippet and injects it into the main content area without reloading the page.
FAQ
Is Hugo Minimalist SPA free?
Yes, the theme is open source and released under the MIT License, so you can use it for personal or commercial projects freely.
What are the requirements to use this theme?
You need Hugo installed; the author recommends Hugo 0.48 or higher, but it may work with versions above 0.43. No other dependencies are required — the JavaScript core only uses jQuery for AJAX.
How do I customize the colors?
Create a theme_style.toml data file in your site's data folder and set the color variables (color_header, color_navbar, color_social_media, color_text, etc.). These are passed directly to the SASS files, so you can use any CSS-supported color.
Can I use custom fonts with this theme?
Yes. Place files named default.otf, default-light.otf, and default-bold.otf in the static/fonts folder, and the theme will automatically use them. Alternatively, you can import custom HTML via custom_imports.html and modify the SASS to use your own font.
Why is my page not loading after I reorder content?
The URLs of each content tab depend on the filename. If you rename or change content files, the AJAX requests may point to old URLs; make sure your browser URL matches the new filenames, and avoid spaces or special characters in filenames to prevent bugs.
