Shibui (渋い)

A minimalist Hugo theme emphasizing simplicity and refinement

Table of contents:

• Features
• Installation
  • As a Git Submodule
  • Configuration
  • Page Configuration
• Color Scheme
• Customization
  • CSS Variables
• Contributing
• License
• Demo
• Theme Structure
  • Template Organization
  • Assets
  • ExampleSite
• Updating
• Version Requirements
• Credits

Shibui (渋い) (adjective), shibumi (渋み) (subjective noun), or shibusa (渋さ) (objective noun) are Japanese words that refer to a particular aesthetic of simple, subtle, and unobtrusive beauty. Like other Japanese aesthetics terms, such as iki and wabi-sabi, shibui can apply to a wide variety of subjects, not just art or fashion.

• Minimalist design following Shibui (渋い) aesthetics
• Terminal-inspired navigation
• Clean typography with monospace font
• Semantic HTML with proper text styling (bold, italic, blockquotes)
• Paper-like color scheme
• Automatic dark/light theme support
• Nested heading counters
• Zero JavaScript (pure CSS solutions)
• Highly customizable through CSS variables
• Mobile-responsive layout
• Table of Contents support
• Tags support
• Customizable

git submodule add https://github.com/ntk148v/shibui.git themes/shibui
git submodule update --init --recursive

Add the following to your config.toml:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'Your Site Title'
theme = "shibui"

[params]
  author = "Your Name"
  email = "your.email@example.com"

[menu]
  [[menu.main]]
    name = "Posts"
    url = "/posts/"
    weight = 1
  [[menu.main]]
    name = "About"
    url = "/about/"
    weight = 2

In the front matter of your content files:

---
title: "Your Post Title"
date: 2023-06-13
tags: ["hugo", "theme"]
---

The theme uses a paper-like color palette, use a background primary color as base and then derive the rest of theme colors by shifting lightness (or saturation/hue if needed) relative to that base, so we can easily generate multiple variants (light, dark, high-contrast, etc.). Therefore, you can adjust just base color and keep the same vibe, checkout #4 for preview.

/* Base theme knobs */
--bg-h: 0;
--bg-s: 0%;
--bg-l: 99%;

/* Background colors */
--color-bg-primary: hsl(var(--bg-h) var(--bg-s) var(--bg-l));
--color-bg-secondary: hsl(var(--bg-h) var(--bg-s) calc(var(--bg-l) - 2%));
--color-border: hsl(var(--bg-h) var(--bg-s) calc(var(--bg-l) - 6%));
--color-selection-bg: hsl(var(--bg-h) var(--bg-s) calc(var(--bg-l) - 13%));

/* Text colors with WCAG-friendly contrast */
/* Primary: ensures near-black on light bg and near-white on dark bg */
--color-text-primary: hsl(
  var(--bg-h) var(--bg-s) clamp(8%, calc(100% - var(--bg-l)), 92%)
);

/* Muted: softer but still >4.5:1 contrast */
--color-text-muted: hsl(
  var(--bg-h) var(--bg-s) clamp(30%, calc(85% - var(--bg-l)), 75%)
);

/* Code text: slightly brighter than muted */
--color-text-code: hsl(
  var(--bg-h) var(--bg-s) clamp(20%, calc(90% - var(--bg-l)), 85%)
);

You can customize the theme by overriding CSS variables in your assets/css/custom.css:

For example, you want to create a dark theme, just adjust the base color.

:root {
  /* Base theme knobs */
  --bg-h: 0;
  --bg-s: 0%;
  --bg-l: 12%;
}

Contributions are welcome! Primary goals are:

• Maintain minimalist design principles
• Keep it simple and efficient
• Avoid JavaScript when CSS can solve the problem
• Follow Shibui (渋い) aesthetics

MIT

Visit the demo site to see the theme in action.

shibui/
├── archetypes/          # Content template files
├── assets/
│   ├── css/            # Theme CSS files
│   └── js/             # Theme JavaScript files
├── layouts/            # Template files
│   ├── _default/       # Default templates
│   ├── _partials/      # Reusable template parts
│   └── index.html      # Homepage template
├── static/             # Static assets
└── exampleSite/        # Example site for reference

• layouts/_default/baseof.html: Base template with common layout
• layouts/_default/single.html: Template for individual pages
• layouts/_default/list.html: Template for section pages
• layouts/_partials/: Contains reusable components like header, footer
• layouts/index.html: Homepage template

The theme uses a minimal set of assets:

• CSS: Single stylesheet with CSS variables for customization
• JS: Optional JavaScript for enhanced functionality
• Static: Basic favicon and other static assets

The exampleSite directory contains a complete example of a site using the theme. Use it as a reference for:

• Configuration setup
• Content organization
• Front matter examples
• Menu structure

Since the theme is installed as a Git submodule, you can update it to the latest version with:

cd themes/shibui
git pull origin main

• Hugo Extended v0.93.0 or higher
• Go 1.18 or higher (for Hugo modules)

This theme was inspired by various minimalist designs and the Japanese concept of Shibui (渋い). Special thanks to:

• William Jansson
• The Hugo community
• Minimalist design principles
• Japanese aesthetics, particularly Shibui