Minimal Black is a dark-mode-first Hugo theme for personal sites, blogs, and portfolios, offering true black backgrounds, purple accents, and a full set of content layouts and shortcodes. Built by Jim Christopoulos and maintained on GitLab, it runs on Hugo Extended v0.120.0+ with Tailwind CSS and produces static HTML output.
What is Minimal Black?
Minimal Black is an open-source Hugo theme that converts Markdown content into a responsive static website with home, blog, projects, and two about page layouts. It outputs clean HTML with client-side search, syntax-highlighted code blocks, and a modular CSS architecture. The theme is distributed under the MIT License and includes an example site for quick setup.
Key Features
- Dark & Light Mode — Auto-switches based on system preference, with a manual toggle; dark mode uses true black (#000000) with purple (#a855f7) accents.
- Client-Side Search — Fast search with Ctrl/Cmd+K shortcut, using Hugo's JSON output for instant results.
- Content Layouts — Home, blog, projects, and two about page variants, including timeline entries and experience cards.
- Shortcodes — Gallery with lightbox, GitHub-style alerts (note, tip, important, warning, danger), and Mermaid diagram support.
- Analytics Ready — Built-in configuration parameters for Google Analytics, Plausible, Umami, and Fathom.
- Icon Libraries — Integrates Font Awesome and Devicon for social links and tech stack icons.
- Code Highlighting — Syntax highlighting with a copy button and language labels on code blocks.
- Table of Contents — Auto-generated TOC for blog posts with active section tracking.
Who is it for?
- Developers building a personal portfolio or blog with code snippets and project showcases.
- Technical writers who need GitHub-style alerts, Mermaid diagrams, and a clean reading experience.
- Design-conscious creators who want a responsive, mobile-first site with a modern dark aesthetic.
What can you do with Minimal Black?
- Create a personal site by adding the theme as a Git submodule, copying the example config, and running
hugo server -D. - Publish a blog with Markdown files, auto-generated table of contents, and searchable content.
- Showcase projects using the projects layout with GitHub and demo links, plus a tech stack display on the homepage.
- Deploy to Netlify using the included
netlify.tomlwith build commandhugo --minifyand environment variables for Hugo v0.120.0 and Node 18.
How does Minimal Black work?
The theme uses Hugo's template system with layouts, partials, and shortcodes, combined with Tailwind CSS for styling. Content is authored in Markdown with front matter for titles, dates, tags, and custom fields. The quick start involves creating a Hugo site, cloning or submoduling the repository into themes/minimal-black, running npm install to compile Tailwind, and copying the example configuration.
Pricing and License
Minimal Black is free and open source under the MIT License. There are no paid tiers, and it can be freely used in commercial projects or modified.
FAQ
Is Minimal Black free?
Yes, the theme is released under the MIT License, so you can use it at no cost, including in commercial work.
What prerequisites do I need?
Hugo Extended v0.120.0 or higher and Node.js with npm are required to compile Tailwind CSS and run the theme.
How do I enable search?
Ensure your site configuration includes JSON output by adding home = ["HTML", "RSS", "JSON"] under the [outputs] section of hugo.toml.
Can I customize the accent color?
Yes, edit CSS variables in assets/css/base.css, where the dark and light palettes are defined separately.
Which analytics platforms are supported?
Google Analytics (GA4), Plausible, Umami, and Fathom are supported through configuration parameters.
