BuGuTheme

A minimalist, content-focused Hugo theme with masonry layout, featured carousel, photo stack, client-side search, lightbox, and built-in Chinese/English i18n.

Features

Masonry card grid — responsive 2-column layout on desktop, single column on mobile
Featured carousel — hero slider for featured posts with cover images, categories, subtitles
Article page — clean typography with optional floating TOC sidebar, prev/next navigation, tags, Giscus comments
Photo stack — interactive flipable photo gallery via {{< photos >}} shortcode
AI Summary — collapsible AI-generated summary block via {{< ai-summary >}}
AI Warning — dismissible AI disclosure notice via {{< ai-warning >}}
References — styled reference list via {{< refers >}} + {{< refer >}}
Client-side search — Fuse.js fuzzy search with modal UI
Image lightbox — click to enlarge images in article content
Dark mode — system-aware theme toggle with persistent preference
i18n — Chinese (zh-CN) and English (en) translations for all UI text
Custom scrollbar — thin overlay-style scrollbar, no layout width
Progress bar — subtle top-of-page loading indicator
Responsive — adapts from 4K down to mobile (320px)
Google Analytics — optional tracking code
Giscus — optional comment integration via GitHub Discussions

Quick Start

1. Create a new Hugo site

hugo new site my-blog
cd my-blog

2. Install the theme

Option A — Git submodule (recommended)

git init
git submodule add https://github.com/GuGuDaDaDa/BuGuTheme.git themes/bu-gu-theme

Option B — Copy directly

Copy the entire theme folder into themes/bu-gu-theme/.

3. Configure your site

Replace hugo.toml in your project root with:

baseURL = 'https://yoursite.com/'
defaultContentLanguage = 'zh-cn'
theme = 'bu-gu-theme'

[markup]
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 3

# ── Language: Chinese (default) ──
[languages.'zh-cn']
  locale = 'zh-CN'
  title = '你的博客名'
  hasCJKLanguage = true
  weight = 10

  [[languages.'zh-cn'.menus.main]]
    identifier = 'home'
    name = '首页'
    pageRef = '/'
    weight = 10

  [[languages.'zh-cn'.menus.main]]
    identifier = 'categories'
    name = '分类'
    pageRef = '/categories'
    weight = 20

  [[languages.'zh-cn'.menus.main]]
    identifier = 'tags'
    name = '标签'
    pageRef = '/tags'
    weight = 30

  [[languages.'zh-cn'.menus.main]]
    identifier = 'about'
    name = '关于'
    pageRef = '/about'
    weight = 40

  [[languages.'zh-cn'.menus.main]]
    identifier = 'friends'
    name = '友链'
    pageRef = '/friends'
    weight = 50

  [languages.'zh-cn'.params]
    footerText = '你的博客名 · 一句话描述'
    copyright = '你的博客名'       # © 年份 + 此处文字；留空则用 title
    themeName = 'BuGuTheme'        # footer 主题名；留空显示 "mytheme"
    themeURL  = 'https://github.com/GuGuDaDaDa/BuGuTheme'  # 主题链接；留空则不生成链接
    giscusRepo = ''                # GitHub 仓库（如 "user/repo"）
    giscusRepoId = ''              # 仓库节点 ID
    giscusCategory = ''            # Discussion 分类名
    giscusCategoryId = ''          # 分类节点 ID
    icp = ''
    [languages.'zh-cn'.params.social]
      github = 'https://github.com/yourname'
      twitter = ''
      email = ''

# ── Language: English ──
[languages.en]
  locale = 'en'
  title = 'Your Blog'
  weight = 20

  [[languages.en.menus.main]]
    identifier = 'home'
    name = 'Home'
    pageRef = '/'
    weight = 10

  [[languages.en.menus.main]]
    identifier = 'categories'
    name = 'Categories'
    pageRef = '/categories'
    weight = 20

  [[languages.en.menus.main]]
    identifier = 'tags'
    name = 'Tags'
    pageRef = '/tags'
    weight = 30

  [[languages.en.menus.main]]
    identifier = 'about'
    name = 'About'
    pageRef = '/about'
    weight = 40

  [[languages.en.menus.main]]
    identifier = 'friends'
    name = 'Friends'
    pageRef = '/friends'
    weight = 50

  [languages.en.params]
    footerText = 'Your Blog · A catchy tagline'
    copyright = 'Your Blog'
    themeName = 'BuGuTheme'
    themeURL  = 'https://github.com/GuGuDaDaDa/BuGuTheme'
    giscusRepo = ''                # GitHub repo (e.g., "user/repo")
    giscusRepoId = ''              # Repository node ID
    giscusCategory = ''            # Discussion category name
    giscusCategoryId = ''          # Category node ID
    icp = ''
    [languages.en.params.social]
      github = 'https://github.com/yourname'
      twitter = ''
      email = ''

Single-language use: If you only need Chinese, remove the [languages.en] section. If only English, change defaultContentLanguage to en and remove the [languages.'zh-cn'] section.

4. Create content

Blog posts

Create posts under content/posts/:

hugo new content posts/my-first-post.md

+++
title = 'My First Post'
date = 2026-01-15T09:00:00+08:00
description = 'A brief description for the card'
subtitle = 'Optional subtitle shown in the carousel'
featured = true          # show in carousel
categories = ['tech']
tags = ['hugo', 'blog']
cover = 'cover.jpg'      # image in the same directory, or external URL
toc = true               # show table of contents sidebar
draft = false
+++

Your content here...

Place the cover image (cover.jpg) in the same directory as your post's index.md (page bundle).

About page

Create content/about/index.md:

+++
title = 'About'
layout = 'about'
description = 'A short tagline under your name'
+++

Write your bio here in Markdown.

Optionally set `github`, `twitter`, `email` in frontmatter to show social links:
+++
title = 'About'
layout = 'about'
github = 'https://github.com/yourname'
email = 'hello@example.com'
+++

Place your avatar as avatar.jpg or avatar.png in content/about/.

Friends (blogroll) page

Create content/friends/_index.md:

+++
title = 'Friends'
layout = 'friends'
+++

Then create data/friends.yaml (or friends.json / friends.toml) in your project root:

# data/friends.yaml
- name: "Friend's Blog"
  url: "https://example.com"
  avatar: "https://example.com/avatar.jpg"
- name: "Another Blog"
  url: "https://example.org"
  avatar: "https://example.org/avatar.jpg"

Each entry requires:

name — displayed name
url — link target
avatar — image URL (Gravatar, static image, or external)

5. Run

hugo server -D

Visit http://localhost:1313/.

Shortcodes

Photos — interactive photo stack

{{< photos >}}
{{< photo src="img1.jpg" caption="Caption one" >}}
{{< photo src="img2.jpg" >}}
{{< photo src="img3.jpg" caption="Caption three" >}}
{{< /photos >}}

Each {{< photo >}} is one image. caption is optional. Supports click, keyboard (arrow keys), and touch swipe to flip through photos.

Parameter	Type	Description
`src`	string	Image filename (page resource) or external URL
`caption`	string	Optional caption shown below the image

AI Summary — collapsible summary block

Renders a collapsible panel labeled "AI 摘要". Click the toggle button to expand or collapse. State resets on page reload (no localStorage).

{{< ai-summary >}}
本文探讨了……（支持 Markdown）
{{< /ai-summary >}}

AI Warning — dismissible disclosure notice

Renders a dismissible notice bar with a left accent line and a close button. Closing hides it for the current page session only (no localStorage).

{{< ai-warning title="透明声明" >}}
本文部分内容在 AI 辅助下完成，所有文字均经过作者逐段审校与修改。
{{< /ai-warning >}}

Parameter	Type	Default	Description
`title`	string	—	Bold prefix before the notice text; omit to show plain text only

References — styled reference list

Use {{< refers >}} as the container and one {{< refer >}} per entry. The list is auto-numbered via CSS counter; pass num to override.

{{< refers >}}
{{< refer desc="文章或书籍标题" url="https://example.com" >}}
{{< refer desc="另一篇参考，无需链接" >}}
{{< refer num="*" desc="用星号或自定义标记代替序号" url="https://example.org" >}}
{{< /refers >}}

{{< refers >}} accepts an optional title parameter (default: 参考资料):

{{< refers title="References" >}}
…
{{< /refers >}}

Parameter	Type	Default	Description
`desc` (or positional `0`)	string	—	Description / title of the reference
`url` (or positional `1`)	string	—	Link URL; omit to render plain text
`num`	string	auto	Override the sequence number badge

Frontmatter Reference

Field	Type	Description
`title`	string	Post title
`date`	datetime	Publication date
`lastmod`	datetime	Last modified date
`description`	string	Short description (card excerpt + carousel subtitle fallback)
`subtitle`	string	Carousel subtitle (shown between title and meta)
`featured`	bool	Show in the homepage carousel
`categories`	array	Category names
`tags`	array	Tag names
`cover`	string	Cover image filename (page resource) or external URL
`toc`	bool	Show table of contents sidebar on this article
`draft`	bool	Draft mode (not published)
`layout`	string	Page layout: `"about"` or `"friends"`

Directory Structure (user project)

my-blog/
├── hugo.toml               # site configuration
├── content/
│   ├── posts/
│   │   ├── hello-world/
│   │   │   ├── index.md    # post content
│   │   │   └── cover.jpg   # cover image
│   │   └── another-post.md # flat file without cover
│   ├── about/
│   │   ├── index.md        # about page
│   │   └── avatar.jpg      # your avatar
│   └── friends/
│       └── _index.md       # friends page
├── data/
│   └── friends.yaml        # friends list (.yaml / .json / .toml)
├── assets/                 # optional: override theme assets
├── static/                 # static files (images, etc.)
└── themes/
    └── bu-gu-theme/        # the theme

Site Params Reference

All params live under [languages.<lang>.params] in hugo.toml.

Param	Type	Default	Description
`footerText`	string	—	Slogan shown in the footer center, e.g. `博客名 · 一句话描述`
`copyright`	string	site `title`	Name shown after © in the footer meta row
`themeName`	string	`"mytheme"`	Theme name shown in the footer "Theme" link
`themeURL`	string	—	URL for the theme name link; omit to render plain text
`icp`	string	—	ICP license number (shown below footer slogan, China only)
`social.github`	string	—	Full GitHub profile URL
`social.twitter`	string	—	Full Twitter/X profile URL
`social.email`	string	—	Email address (generates `mailto:` link)
`giscusRepo`	string	—	GitHub repo (e.g., `user/repo`) for Giscus comments
`giscusRepoId`	string	—	Repository node ID from GitHub
`giscusCategory`	string	—	Discussion category name
`giscusCategoryId`	string	—	Discussion category node ID
`giscusMapping`	string	`pathname`	Mapping between page and discussion
`giscusReactionsEnabled`	string	`1`	Enable reactions (`1` or `0`)
`giscusLang`	string	site lang	Interface language for Giscus
`googleAnalytics`	string	—	Google Analytics measurement ID

Browser Support

Chrome, Firefox, Safari, Edge (latest 2 versions). Requires Hugo >= 0.146.0.

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
archetypes		archetypes
assets		assets
i18n		i18n
layouts		layouts
static		static
.gitignore		.gitignore
README.md		README.md
hugo.toml		hugo.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

BuGuTheme

Features

Quick Start

1. Create a new Hugo site

2. Install the theme

3. Configure your site

4. Create content

Blog posts

About page

Friends (blogroll) page

5. Run

Shortcodes

Photos — interactive photo stack

AI Summary — collapsible summary block

AI Warning — dismissible disclosure notice

References — styled reference list

Frontmatter Reference

Directory Structure (user project)

Site Params Reference

Browser Support

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

BuGuTheme

Features

Quick Start

1. Create a new Hugo site

2. Install the theme

3. Configure your site

4. Create content

Blog posts

About page

Friends (blogroll) page

5. Run

Shortcodes

Photos — interactive photo stack

AI Summary — collapsible summary block

AI Warning — dismissible disclosure notice

References — styled reference list

Frontmatter Reference

Directory Structure (user project)

Site Params Reference

Browser Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages