mnml for Hugo

A clean and simple minimalist theme for Hugo, ported from the mnml Micro.blog theme by Jim Mitchell.

View Demo • Built for speed with excellent Lighthouse scores:

Quick Start

# Add theme to your Hugo site
cd your-hugo-site
git submodule add https://github.com/shawnyeager/mnml-hugo.git themes/mnml-hugo

# Copy example configuration
cp themes/mnml-hugo/exampleSite/hugo.toml hugo.toml

# Create your first post
hugo new content/post/my-first-post.md

# Start the server
hugo server

Other Installation Methods

Clone Method

cd your-hugo-site/themes
git clone https://github.com/shawnyeager/mnml-hugo.git

Hugo Modules (requires Go)

In your hugo.toml:

[module]
  [[module.imports]]
    path = "github.com/shawnyeager/mnml-hugo"

Requirements

Hugo Extended v0.151.0+ — Required for image processing features (WebP optimization, responsive images). Standard Hugo works but without image optimization.

Features

Core Features

🌍 12 languages supported with full i18n
🌓 Light/dark mode with automatic system detection
📱 Mobile responsive design
🔍 Built-in search functionality
📄 Pagination on all post-related pages

Content & Media

🖼️ Advanced image processing (WebP, responsive srcset: 400w/800w/1200w)
📸 Photo layouts (grid or masonry)
🎥 Automatic video embedding (MP4, MOV, WebM)
📝 Microblog-style titleless posts

Customization

🎨 Category filtering for home page and photos
📌 Pinned posts by category
🖥️ Header width options (wide or narrow)
📅 Date format options (short or long)
👤 Custom avatars or hide avatar entirely
🗃️ Archive years filtering for posts by year
🐘 Fediverse Creator tag support

View all features

Featured post category setting
Custom home page category setting
Multiple, comma-separated home page categories
Display full posts on category pages
Custom photos page category setting
Wide or narrow photo page layout setting
Show all image formats on photos page
Show only first image from multi-image posts
Reading time display
Category counts on archive pages
Customizable search results count
RSS feed customization
Footer customization options

Configuration

Copy exampleSite/hugo.toml to your site for a complete working configuration. All parameters are optional with sensible defaults.

Essential Configuration

baseURL = "https://example.com/"
languageCode = "en"
title = "My Blog"
theme = "mnml-hugo"
defaultContentLanguage = "en"

[pagination]
  pagerSize = 20

[permalinks]
  post = "/:filename/"

[taxonomies]
  category = "categories"
  tag = "tags"

[outputs]
  home = ["HTML", "RSS", "archivejson"]
  section = ["HTML", "RSS"]
  archive = ["HTML", "archivehtml"]  # Required for archive_years feature

[outputFormats.RSS]
  mediaType = "application/rss+xml"
  baseName = "feed"

[outputFormats.archivejson]
  mediaType = "application/json"
  baseName = "archive/index"
  isPlainText = true
  notAlternative = true

[outputFormats.archivehtml]
  mediaType = "text/html"
  baseName = "index"

[params]
  description = "A minimal, simple and clean blog."
  itunes_description = "A minimal, simple and clean blog."
  theme_seconds = "1"  # Cache busting version

# Image processing settings (Hugo Extended only)
[imaging]
  quality = 85
  resampleFilter = "Lanczos"
  anchor = "Smart"

[imaging.exif]
  disableDate = false
  disableLatLong = true

Theme Parameters Reference

Date & Time

Parameter	Type	Default	Description
`use_short_date`	boolean	false	Use short date format
`show_read_time`	boolean	true	Show reading time on posts

Header & Avatar

Parameter	Type	Default	Description
`narrow_header`	boolean	false	Use narrow header width
`hide_avatar`	boolean	false	Hide site avatar
`custom_avatar`	string	-	URL to custom avatar image

Home Page

Parameter	Type	Default	Description
`home_category`	string	-	Filter by category (comma-separated for multiple)
`pinned_category`	string	"Pinned"	Category for pinned post
`show_full_post`	boolean	false	Show full posts vs summaries

Category/Archive Pages

Parameter	Type	Default	Description
`category_full_post`	boolean	false	Show full posts on category pages
`show_categories`	boolean	true	Show category list on archives
`show_category_count`	boolean	true	Show post counts on category tags
`archive_years`	boolean	false	Enable year filtering on archive page*

*Archive Years Feature: Adds a dropdown to filter archive posts by year. Based on the Archive Years plugin by Jim Mitchell. Requires archivehtml output format.

Photos

Parameter	Type	Default	Description
`photos_category`	string	"Photos"	Filter photos by category
`all_formats`	boolean	false	Show all image formats
`masonry_layout`	boolean	false	Use masonry layout (false = grid)
`full_width_photos`	boolean	false	Use wider photos layout
`single_image`	boolean	false	Show only first image

Search

Parameter	Type	Default	Description
`search_results`	integer	5	Number of search results to display

Footer

Parameter	Type	Default	Description
`hide_copyright`	boolean	false	Hide copyright notice
`footer_rss`	boolean	true	Add RSS link to footer
`hide_credit`	boolean	false	Hide theme credits

Advanced

Parameter	Type	Default	Description
`fediverse_creator`	string	-	Fediverse creator tag (e.g., @user@mastodon.social)
`archive-paginate`	integer	30	Archive page size

Creating Content

Regular Posts

---
title: "My First Post"
date: 2025-10-06T10:00:00-00:00
categories: ["Blog"]
---

Your content here...

Posts go in content/post/ directory.

Microblog Posts

Omit the title for microblog-style posts:

---
date: 2025-10-06T10:00:00-00:00
---

Just a quick thought...

Photo Posts

Add photos using standard markdown image syntax. Store images in assets/images/ for automatic processing:

---
title: "My Photo Collection"
date: 2025-10-06T10:00:00-00:00
categories: ["Photos"]
---

Optional description...

![Alt text](images/photo1.jpg)
![Alt text](images/photo2.jpg)

Image Processing (Hugo Extended):

Auto-converted to WebP format
3 responsive sizes generated (400w, 800w, 1200w)
Lazy loading and proper dimensions
Cached in resources/ for fast rebuilds

Store images in assets/images/ (processed) or static/images/ (served as-is).

Note: The photos frontmatter array is deprecated but still supported for backward compatibility with Micro.blog imports. New posts should use markdown image syntax instead.

Video Posts

Videos (.mp4, .mov, .webm) are automatically embedded. Store in static/images/:

Simple video:

[Video description](images/video.mp4)

With poster image:

[Video description](images/video.mp4 "images/poster.png")

Automatically converts to HTML5 video players with controls.

Search Page

Create content/search.md:

---
title: "Search"
---

{{< search >}}

Add to menu in hugo.toml:

[[menu.main]]
  name = "Search"
  url = "/search/"
  weight = 4

Customization

Custom CSS

Override theme styles by creating static/css/custom.css in your site:

/* Light mode */
:root {
  --text-color: #333333;
  --link-color: #0d88d8;
  --background: #FFFFFF;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --text-color: #FFFFFF;
    --link-color: #45c8f7;
    --background: #20232a;
  }
}

See the Micro.blog customization guide for more examples.

Languages

Supports 12 languages: English, German, Spanish, Finnish, French, Italian, Polish, Portuguese, Russian, Swedish, Ukrainian, Chinese (Traditional).

Set in hugo.toml:

defaultContentLanguage = "de"

Development

cd exampleSite
hugo server --themesDir ../..

Visit http://localhost:1313

Differences from Micro.blog Version

This Hugo port differs from the Micro.blog plugin:

Configuration: Uses hugo.toml instead of Micro.blog's web UI
Content structure: Posts go in content/post/ directory
Platform features: Some Micro.blog-specific features may not be available
Stub partials: Includes empty stub files for microblog_head.html and custom_footer.html

Credits & Support

Original Theme: Jim Mitchell • github.com/jimmitchell/mnml Hugo Port: Shawn Yeager • github.com/shawnyeager/mnml-hugo

Localization Contributors

Swedish: @robertbirming
Ukrainian & Russian: @luxury-format
Chinese (Traditional): @bobbytung
Polish: @bstn

Support

If you enjoy mnml, consider supporting Jim Mitchell ☕

License: MIT

Name		Name	Last commit message	Last commit date
Latest commit History 684 Commits
exampleSite		exampleSite
i18n		i18n
layouts		layouts
static		static
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
hugo.toml.example		hugo.toml.example
icon.jpg		icon.jpg
lighthouse-scores.png		lighthouse-scores.png
plugin.json		plugin.json
theme.toml		theme.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

mnml for Hugo

Quick Start

Clone Method

Hugo Modules (requires Go)

Requirements

Features

Core Features

Content & Media

Customization

Configuration

Date & Time

Header & Avatar

Home Page

Category/Archive Pages

Photos

Search

Footer

Advanced

Creating Content

Regular Posts

Microblog Posts

Customization

Custom CSS

Languages

Development

Credits & Support

Localization Contributors

Support

About

Uh oh!

Releases 2

Packages

Languages

License

shawnyeager/mnml-hugo

Folders and files

Latest commit

History

Repository files navigation

mnml for Hugo

Quick Start

Clone Method

Hugo Modules (requires Go)

Requirements

Features

Core Features

Content & Media

Customization

Configuration

Date & Time

Header & Avatar

Home Page

Category/Archive Pages

Photos

Search

Footer

Advanced

Creating Content

Regular Posts

Microblog Posts

Customization

Custom CSS

Languages

Development

Credits & Support

Localization Contributors

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages