Minimal Black Hugo Theme

A comprehensive Hugo theme designed for developers, designers, and everyone in general who value simplicity, performance, and beautiful dare I say dark mode design (maybe?).

Overview

Minimal Black is a modern Hugo theme that combines aesthetic appeal with practical functionality.

Built with Tailwind CSS and a modular architecture, it provides everything you need for a professional personal website, portfolio or blog.

Key Features

• True Black Dark Mode — With purple accents
• Responsive Design — Perfect on mobile, tablet, and desktop
• Search Functionality — Fast client-side search with Ctrl/Cmd+K
• Table of Contents — Auto-generated
• Syntax Highlighting — Beautiful code blocks with copy functionality
• Multiple Layouts — Flexible page templates for different content types (more to come hopefully).

Technical Architecture

Frontend Stack

• Hugo Extended (v0.120.0+) — Static site generator
• Tailwind CSS — Utility-first CSS framework
• Vanilla JS — Minimal JS used - no framework
• PostCSS — CSS processing and optimization

CSS Modular Structure

The CSS is organized into logical modules:

assets/css/
├── base.css          # Theme variables & Tailwind
├── utilities.css     # Helper classes
├── components/       # Reusable UI components
│   ├── dock.css
│   ├── cards.css
│   ├── navigation.css
│   ├── search.css
│   └── tech-marquee.css
├── content/          # Content-specific styles
│   ├── markdown.css
│   └── toc.css
└── pages/            # Page-specific styles
    ├── about.css
    └── about-alternative.css

This modular approach makes the theme:

• Easy to maintain and extend
• Simple to customize specific components
• Clear separation of concerns
• Better developer experience

Design Philosophy

Minimalism First

The theme embraces minimalism without sacrificing functionality:

1. Clean Typography — Careful font choices and spacing
2. Focused Content — Remove distractions, highlight what matters
3. Subtle Animations — Smooth transitions that enhance UX
4. Dark Mode Priority — True black backgrounds

Feature Showcase

Search Functionality

Built-in search with keyboard shortcuts:

• Press Ctrl/Cmd + K to open search
• Type to filter results in real-time
• Use Arrow keys to navigate
• Press Enter to visit page
• ESC to close

The search is client-side, fast, and requires no external services.

Code Blocks

Beautiful syntax highlighting with practical features:

// Copy button on hover
function greet(name) {
  console.log(`Hello, ${name}!`);
  return `Welcome to Minimal Black Theme`;
}

greet("Developer");

Features include:

• Language labels
• Copy to clipboard button
• Line highlighting
• Collapsible / Expandable block

GitHub-Style Alerts

Support for callout boxes:

Table of Contents

MD content automatically gets a TOC:

• Sticky Positioning — Stays visible while scrolling
• Active Tracking — Highlights current section
• Smooth Scrolling — Click to jump to section
• Responsive — Hides on mobile, shows on desktop

You’re seeing it in action on this page!

Mermaid Diagrams

Native support for flowcharts and diagrams:

graph TD
    A[User visits site] --> B{Dark mode?}
    B -->|Yes| C[Load dark theme]
    B -->|No| D[Load light theme]
    C --> E[Render content]
    D --> E
    E --> F[Fast, beautiful site]
  

Perfect for technical documentation.

Configuration

The theme is highly configurable via hugo.toml:

Basic Setup

[params]
  brand = "Your Name"
  description = "Your site description"
  
  [params.theme]
    defaultTheme = "dark"  # or "light" or "system"

Hero Section

[params.hero]
  badge = "Software Engineer"
  title = "Hi, I'm Your Name."
  role = "Building things."
  summary = "Description of what you do."
  location = "City, Country"

Tech Stack Display

[[params.home.tech]]
  label = "Python"
  icon = "devicon-python-plain"

[[params.home.tech]]
  label = "Docker"
  icon = "devicon-docker-plain"

Analytics

Support for multiple providers:

[params.analytics]
  googleAnalytics = "G-XXXXXXXXXX"
  
  # Or use Plausible, Umami, Fathom

Customization Guide

Colors

Theme colors are CSS custom properties in assets/css/base.css:

:root {
  --color-bg: #f9fafb;        /* Light background */
  --color-accent: #a855f7;     /* Purple accent */
}

html[data-theme="dark"] {
  --color-bg: #000000;         /* True black */
  --color-accent: #c084fc;     /* Lighter purple */
}

Adding Custom Styles

Create assets/css/custom.css in your site:

/* Your custom styles */
.my-custom-class {
  /* ... */
}

Then reference it in your config:

[params]
  customCSS = ["css/custom.css"]

Content Organization

Recommended Structure

content/
├── _index.md           # Homepage
├── about.md            # About page
├── blog/
│   ├── _index.md
│   └── posts/
├── projects/
│   ├── _index.md
│   └── individual-projects/
└── pages/
    └── custom-pages/

Frontmatter Examples

Blog Post:

+++
title = "Post Title"
date = "2025-01-15"
tags = ["hugo", "web-dev"]
categories = ["tutorials"]
draft = false
+++

Project:

+++
title = "Project Name"
description = "Brief description"
github = "https://github.com/..." # Optional
demo = "https://demo.com" # Optional
featured = true
+++

Deployment

Netlify

1. Connect your Git repository
2. Build command: hugo --minify
3. Publish directory: public
4. Environment: HUGO_VERSION=0.120.0

Vercel

1. Import repository
2. Framework: Hugo
3. Build command: cd themes/minimal-black && npm install && cd ../.. && hugo --minify
4. Output: public

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

Released under the MIT License. See LICENSE for details.

Acknowledgments

Built with:

• Hugo — Static site generator
• Tailwind CSS — CSS framework
• Font Awesome — Icons
• Devicon — Technology icons

Repository: GitLab

Demo: Live Preview

Documentation: Full Docs