Beautiful Hugo

An adaptation of the Beautiful Jekyll theme by Dean Attali, with years of community updates and many new features.

Live demo

• Current: https://halogenica.net/beautifulhugo
• Legacy: https://hugo-theme-beautifulhugo.netlify.app

The example site includes detailed feature pages with live examples — see Features below.

Installation

Install Hugo and create a new site. See the Hugo documentation for details.

Git Submodule

git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo

A submodule points to a commit, not to a tag. To use a release, check out the tag in the submodule and commit the result:

git -C themes/beautifulhugo checkout v5.0.0
git add themes/beautifulhugo

Hugo Module

hugo mod init github.com/USERNAME/SITENAME
hugo mod get github.com/halogenica/beautifulhugo/v5

The /v5 suffix is the major version of the theme. Pin an exact release with hugo mod get github.com/halogenica/beautifulhugo/v5@v5.0.0, or stay up to date with hugo mod get -u.

If using Hugo modules, add this to your hugo.toml:

[[module.imports]]
  path = "github.com/halogenica/beautifulhugo/v5"

Preview

Copy the example site content and start Hugo:

cp -riv themes/beautifulhugo/exampleSite/* .
hugo serve

Features

For complete configuration reference, shortcode documentation, and live examples, see the example site feature pages:

• Configuration — every hugo.toml parameter
• Shortcodes — details, columns, tabs, gallery, video, mermaid
• Code Blocks — Chroma vs Highlight.js, line numbers, copy button
• Markdown Extensions — callout boxes, theme-dependent content
• Figures & Galleries — PhotoSwipe integration
• Math & Diagrams — KaTeX and Mermaid examples
• Layout Options — big images, full-width, hidden pages (part of Pages & Layouts)
• Comments & Social — comment systems, social sharing, footer icons
• SEO & i18n — structured data, Open Graph, multilingual

Quick Start Config

baseurl = "https://example.com/"
title = "My Site"

[Params]
  subtitle = "Build a beautiful and simple website in minutes"
  mainSections = ["post", "posts"]
  logo = "/img/avatar-icon.png"
  favicon = "/img/favicon.ico"
  dateFormat = "January 2, 2006"
  colorScheme = "auto"
  readingTime = true
  socialShare = true
  showRelatedPosts = true
  rss = true

  [Params.search]
    provider = "fuse"

[Params.author]
  name = "Your Name"
  website = "yourwebsite.com"
  email = "youremail@domain.com"
  github = "username"

[markup.highlight]
  noClasses = false

[markup.goldmark.parser.attribute]
  block = true

[markup.goldmark.renderer]
  unsafe = true

Note: [Params.author] is required. The old top-level [author] key is deprecated and will produce a build error.

License

MIT Licensed, see LICENSE.