Stacknote is a warm editorial Hugo theme for technical notes and personal engineering blogs, turning Markdown content into a responsive static site with search and structured metadata.
What is Stacknote?
Stacknote is an open-source Hugo theme hosted in the myimilo/hugo-theme-stacknote GitHub repository, designed to publish field-tested engineering notes. It takes Markdown files written for Hugo (articles under a content section such as content/articles) and produces a static website that includes responsive editorial homepages, article lists, taxonomies, archives, a search page, and an author page. The theme requires Hugo Extended 0.160.0 or newer because it uses Hugo Pipes to minify CSS/JS, fingerprint assets, and generate WebP cover images.
Key Features
- Editorial typography — A serif display style pairing Cormorant Garamond headlines with Outfit body text and Space Mono accents, loaded from Google Fonts; the CSS provides system fallbacks and can be overridden for offline or privacy-constrained sites.
- Responsive WebP covers — Cover images placed in the site's assets directory are converted by Hugo Pipes into 480, 800, and 1200 pixel WebP variants served with srcset; remote cover URLs are accepted but are not resized.
- Full-text fuzzy search — Search runs client-side against an index.json generated from the home output; it includes title, URL, date, tags, summary, and article text plus loading, empty, error, and retry states; no external search service is required.
- Structured data and social metadata — Article pages emit BlogPosting, ProfilePage, and website JSON-LD, plus Open Graph and Twitter Card tags, with support for local or remote social images.
- Accessibility and reading features — Table of contents, copyable code blocks, previous/next article navigation, related articles, accessible focus states, reduced-motion support, responsive tables, and print styles.
- Configurable homepage sections — About, topics, newsletter, and tag sections can be toggled on or off; English UI strings are kept in Hugo's i18n layer.
- Performance optimizations — Hugo Pipes minification, content fingerprints, and Subresource Integrity hashes protect cached assets.
Who is it for?
- Software engineers who keep a personal engineering blog and want a lightweight static site without a JavaScript framework — they write Markdown and run hugo to deploy.
- Technical writers documenting APIs or systems who need full-text search, an archive page, and tag taxonomies built into the theme.
- Open-source maintainers publishing release notes or technical changelogs who value structured data and social previews out of the box.
- Privacy-conscious site owners who need to self-host fonts by overriding layouts/partials/head.html and assets/css/style.css in their Hugo project.
What can you do with Stacknote?
- Publish a searchable knowledge base: write technical notes under content/articles, enable the JSON home output, and readers get instant fuzzy search with no external dependencies.
- Showcase code-heavy walkthroughs: use code blocks with copy buttons, a heading-anchored table of contents, and related-article suggestions to keep readers engaged.
- Optimize article images automatically: drop a PNG or JPG into the site's assets folder and Stacknote generates compressed WebP versions in three sizes with an alt attribute from front matter.
- Customize the site without editing the theme: Hugo file overrides let you replace any partial or stylesheet while keeping future theme updates clean.
How does Stacknote work?
Install it as a Git submodule with git submodule add https://github.com/myimilo/hugo-theme-stacknote.git themes/stacknote, set theme: stacknote in hugo.yaml, and add content files such as content/articles/_index.md and content/search.md with the appropriate layouts. Configuration lives under params, including author info, homepage intro copy, link URLs, and flags like showToc, showTopics, and showAbout. Search is activated by adding JSON to the home outputs and creating a search page; build output can be verified by checking that /index.json exists.
FAQ
Does Stacknote require a specific Hugo version?
Yes, Stacknote needs Hugo Extended 0.160.0 or newer. Run hugo version and confirm the output contains extended, since the theme relies on Hugo Pipes for asset minification, fingerprinting, and WebP image processing.
Can I use remote or stock images for covers?
Remote image URLs are supported directly in front matter under cover.image. However, remote images are rendered as-is and do not receive the local WebP conversion, srcset resizing, or SRI hashing that images stored in the assets directory enjoy.
How do I enable the search page?
Add JSON to the outputs.home array in your config, create content/search.md with layout: search, and optionally add /search/ to the main menu. Then rebuild and confirm /index.json appears in the public directory. If you do not want search, simply omit both the page and the JSON output.
Is Stacknote a paid theme?
No. Stacknote is released under the MIT License and lives in a public GitHub repository, so it is free to use and modify. No license fees or premium tier are mentioned.
Can I make Stacknote work offline?
The theme loads Cormorant Garamond, Outfit, and Space Mono from Google Fonts by default. To make it fully offline, copy layouts/partials/head.html and assets/css/style.css into your site project and replace the font imports with self-hosted or system fonts.
