hugo-gruvbox

A retro-looking Hugo theme inspired by gruvbox. The pastel colors are high contrast, easily distinguishable, pleasing to the eye, and feature light and dark color palettes.

DISCLAIMER: Project Status

This theme is still under heavy development and not production ready. Check out the issues to see what features are missing. As soon as the core features are implemented, I will publish it to the Hugo showcase and release version v0.1.0.

Quickstart

1. git clone the repository and cd into it
2. Run npm install to install the dependencies
3. Run hugo server

Install The Theme

Create a new Hugo website:

hugo new site example.com
cd example.com/

Initialize the site as Hugo module

hugo mod init example.com

Add the following to the config.toml file:

[markup]
  # (Optional) To be able to use all Prism plugins, the theme enables unsafe
  # rendering by default
  #_merge = "deep"

[build]
  # The theme enables writeStats which is required for PurgeCSS
  _merge = "deep"

# This hopefully will be simpler in the future.
# See: https://github.com/schnerring/hugo-gruvbox/issues/16
[module]
  [[module.imports]]
    path = "github.com/schnerring/hugo-gruvbox"
  [[module.mounts]]
    source = "assets"
    target = "assets"
  [[module.mounts]]
    source = "layouts"
    target = "layouts"
  [[module.mounts]]
    source = "static"
    target = "static"
  [[module.mounts]]
    source = "node_modules/prismjs"
    target = "assets/prismjs"
  [[module.mounts]]
    source = "node_modules/prism-themes/themes"
    target = "assets/prism-themes"
  [[module.mounts]]
    source = "node_modules/typeface-fira-code/files"
    target = "static/fonts"
  [[module.mounts]]
    source = "node_modules/typeface-roboto-slab/files"
    target = "static/fonts"
  [[module.mounts]]
    source = "node_modules/@tabler/icons/icons"
    target = "assets/tabler-icons"
  [[module.mounts]]
    source = "node_modules/simple-icons/icons"
    target = "assets/simple-icons"

Install the theme:

hugo mod get

Initialize the NPM package.json and install the dependencies:

hugo mod npm pack
npm install

Run Hugo:

hugo server

Features

• hugo-json-resume Hugo module to display structured CV data
• Code highlighting with Prism
• Display your CV using JSON Resume
• Full-text search with Flex Search
• Dark mode that also changes Prism themes
• Tabler Icons to display SVG icons
• All third-party dependencies are managed with npm to make updating a breeze and reduce code clutter
• Responsive, mobile-first design
• Automated image processing

Big thanks to the creators of Hugo and the software mentioned above. Also, thanks to everyone participating in open-source. I couldn't have created this theme without you. ❤️

Configuration

Colors

Two options are available to configure the theme colors:

• defaultTheme: dark or light (defaults to light)
  Default theme color for when a user visits the site for the first time.
• themeColor: gray, red, green, yellow, blue, purple, aqua, or orange (defaults to blue)
  Theme color for things such as links, headings etc.
• themeContrast: soft, medium, or hard (defaults to medium)
  Theme background color

Prism

The theme allows customization of Prism via config.toml parameters:

[params]
  [params.prism]
    languages = [
      "markup",
      "css",
      "clike",
      "javascript"
    ]
    plugins = [
      "normalize-whitespace",
      "toolbar",
      "copy-to-clipboard"
    ]

In my opinion, this is the coolest feature of the theme. Other Hugo themes usually include a pre-configured version of Prism, which complicates updates and change tracking, and clutters the theme's code base with third-party JavaScript.

The Prism theme is not configurable because of the integration with the dark mode functionality. Toggling between color modes swaps the Prism theme between gruvbox-dark and gruvbox-light from github.com/PrismJS/prism-themes.

Explore Prism Features

After running npm install, explore Prism features like this:

# Languages
ls node_modules/prismjs/components

# Plugins
ls node_modules/prismjs/plugins

Blog Cover

Configure the cover of a blog post in the front matter. The cover must be part of the page bundle due to image processing.

---
cover:
  src: my-blog-cover.jpg
  alt: A beautiful image containing interesting things
  caption: Source: my imagination
---

Extensibility

You can extend the theme by overriding the following partials in the layouts/partials directory which by default are empty placeholder files:

• head/head_start.html
  Custom HTML at the start of <head>
• head/head_end.html
  Custom HTML at the end of <head>
• footer_end.html
  Custom HTML at the end of <body>
• comments.html
  Comments at the end of posts