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

Hugo Module

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

Stay up to date with hugo mod get.

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

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

Preview

Copy the example site content and start Hugo:

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

Features

Feature	Details
Responsive design	Looks great on desktop and mobile
Light/dark/auto color scheme	Navbar toggle with localStorage persistence
Syntax highlighting	Chroma (server-side, default) or Highlight.js (client-side)
KaTeX math	Inline //(...//) and display $$...$$ — no config needed
Mermaid diagrams	Flowcharts, sequence diagrams, Gantt charts via shortcode
PhotoSwipe galleries	beautifulfigure and gallery shortcodes with lightbox
Shortcodes	details, columns/column, tabs/tab, mermaid, gallery, beautifulfigure
Markdown extensions	Callout boxes (note/warning/error/success), theme-dependent content, utility classes
Comment systems	Disqus, Giscus, Utterances, Cusdis, Staticman
SEO	Schema.org JSON-LD, Open Graph, Twitter Cards — automatic
Multilingual	19 languages with navbar language switcher
Social icons	42 platforms in the footer via [Params.author]
Self-hosted assets	selfHosted = true for GDPR/EU-DSGVO compliance
Big image headers	Full-width hero images with fade cycling
Social sharing	Share buttons on posts (Twitter, Facebook, Reddit, LinkedIn, etc.)
GitHub buttons	Star/watch/fork badges via front matter
Google Analytics	Standard Hugo integration (production only)
Integrated search	Fast client-side search with Fuse.js
RSS	Built-in, enabled with rss = true

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, 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.