Safe default theme for Hugo
add § section links automatically
add css for buttons
remove nav if nothing to show


browse  log 



You can also use your local clone with git send-email.

#Hugo Minimum Viable Theme

license: MPL-2.0 standard-readme compliant

Sane baseline theme for Hugo

#Table of Contents


I got tired of bloated, opinionated, and opaque (to me) Hugo themes, so I'm writing my own. Much of the inspiration comes from the best motherf@#$ing websites, and design details are informed by Matthew Buttrick's Practical Typography. I count this as doing my part to end the website obesity crisis.


git submodule add https://git.sr.ht/stick/hmvt themes/hmvt


Set the proper theme in your hugo configuration file:

  • config.json: "theme": "hmvt"
  • config.toml: theme = 'hmvt'
  • config.yaml: theme: hmvt

#Site Parameters

In addition to the Hugo Site Variables, you can use the following site parameters (in the .Site.Params map) to further customize your site.

Parameter Default Use
Logo Path (within the static folder) to the website's logo image used in the header
Math Enable Katex math typesetting for all pages
RemarkjsCodeTheme "tomorrow-night-eighties" Highlight.js style used for syntax highlighting in presentations
ThemeColor "#0000ff" Set the link color, and theme color for Chrome, Firefox OS, and Opera (six-digit hex color with # prefix)
ThemeColorDark "#8aa1ff" Set the link color for dark mode users (six-digit hex color with # prefix)

When using the ThemeColor and ThemeColorDark parameters, please be aware of accessibility concerns and contrast in general. The default (light) page background is #e6e6e6; the dark mode background is #1a1a1a.

#Page Types

In addition to the "single" and "list" page types, hmvt provides a "remarkjs" type which automatically renders a Remark.js slideshow. To use this type, set type to remarkjs in the page frontmatter.

#Page Parameters

In addition to the Hugo Page Variables, you can use the following page parameters (in the .Page.Params map) to further customize individual pages.

Parameter Default Use
AspectRatio 16:9 Aspect ratio of slides created by Remark.js presentations
Math Enable Katex math typesetting for current page
RemarkjsCodeTheme "tomorrow-night-eighties" Highlight.js style used for syntax highlighting in presentations

#Custom CSS

hmvt provides three opportunities for custom CSS. For each, if a given CSS file exists, it is executed as a Hugo template, minified, and added (with integrity attribute) to specific pages.

  1. assets/css/style.css is added to all pages.

  2. assets/css/syntax.css is added to all pages, except those which have the content type "remarkjs". This allows for generating syntax highlighter CSS, which is necessary if you want different highlighting schemes for light and dark modes, or if you want to avoid allowing inline styles in a Content Security Policy. "remarkjs" pages are omitted, as Remark.js includes Highlighjs already.

  3. assets/css/<content-type>.css files are added to pages with a matching content type.



hmvt provides a custom shortcode to create image slideshows with minimal effort.

{{< slider "image1.png" "image2.svg" "image3.bmp" ... >}}
#YouTube NoCookie

The default Hugo shortcode for YouTube does not use the privacy-enabled youtube-nocookie domain. It also forces its own styles, and does not provide a class to be re-styled with custom CSS. hmvt provides a custom shortcode, ytnc, which rectifies both issues. You can style the .iframe class as desired in a custom css file.

{{< ytnc Xw2D9aJRBY4 >}}


Contributors to this project adhere to the Code of Conduct.

Contributions should use git with discipline.


Copyright © 2019–2020 Stick (stick@stma.is). Where not otherwise specified, this repository is licensed under the Mozilla Public License 2.0.