Blog Module Configuration Guide

noreply@example.com (AG Sayyed) — Thu, 02 Jan 2025 19:43:52 +0000

The HBStack blog module is a comprehensive, modular blogging system that transforms Hugo into a powerful content management platform. Built on Bootstrap 5.3, it provides a complete suite of features including multiple comment systems, advanced sidebar widgets, social integrations, and responsive layouts. The blog module follows a modular architecture where each feature is implemented as a separate sub-module, allowing you to enable only the functionality you need while maintaining optimal performance.

Blog Module Architecture

Blog module works well if you know how to configure it correctly
A blog module is composed of several components, which are themselves made as separate modules being a part of the overall blog module functionality.
If you import a blog module in your repository, all other modules will be imported as well, and you can use its components directly without having to worry about their internal implementation details.
Some of these components being part of the blog module include the following:

Here’s a complete list of modules currently present in the HBStack Blog repository. These are modular Hugo components designed to enhance blogging functionality:

Core Components

Main Blog Engine: Post rendering, layout management, and responsive grid systems
Sidebar System: Modular sidebar with profile, posts, taxonomies, and search widgets
Comment Systems: Multiple commenting platforms (Disqus, Giscus, Utterances, etc.)
Navigation: Breadcrumbs, post navigation, and table of contents with scroll spy
Content Enhancement: Featured images, social sharing, and related posts

Available Blog Sub-Modules

Module	Purpose	Key Features	Configuration Level
`breadcrumb`	Navigation	Hierarchical navigation, customizable separators	Site + Page
`content-panel`	Layout	Flexible content panels, responsive design	Site
`comments/disqus`	Comments	Disqus integration, custom styling	Site
`comments/giscus`	Comments	GitHub Discussions, theme sync	Site
`comments/utterances`	Comments	GitHub Issues, minimal setup	Site
`comments/twikoo`	Comments	Chinese-friendly, cloud database	Site
`comments/staticman`	Comments	Static generation, no external dependencies	Site
`comments/emote`	Comments	Emoji reactions, lightweight	Site
`featured-image`	Media	Automatic image processing, responsive sizing	Page
`heading-sign`	Typography	Permalink anchors, smooth scrolling	Site
`post-nav`	Navigation	Previous/next navigation, related posts	Site
`related-posts`	Discovery	Algorithm-based recommendations, slide/vertical views	Site
`sidebar/profile`	Widget	Author bio, social links, company info	Site
`sidebar/posts`	Widget	Recent/featured posts, multiple display styles	Site
`sidebar/taxonomies`	Widget	Categories, tags, series with counts	Site
`sidebar/search`	Widget	Client-side search, filtering capabilities	Site
`social-share-buttons`	Social	Multi-platform sharing, customizable buttons	Site + Page
`toc-scrollspy`	Navigation	Auto-generated TOC, scroll highlighting	Site + Page

These modules are designed to be composable, meaning you can include only what you need in your Hugo site.

Global Blog Configuration

Core Site Parameters

Add to your hugo.toml:

hugo.toml

 1[params]
 2 [params.hb]
 3 [params.hb.blog]
 4 enabled = true
 5 list_cols_lg = 3
 6 list_cols_md = 2
 7 list_style = 'regular'
 8 post_date_format = '2006-01-02'
 9 post_thumbnail_height = '160px'
10 [params.hb.blog.archives]
11 date_format = '2006-01'
12 list_style = 'compact'
13 paginate = 30
14 [params.hb.blog.home]
15 featured_posts = 5
16 pinned_posts_position = 'top'
17 recent_posts = 10

hugo.yaml

 1params:
 2 hb:
 3 blog:
 4 archives:
 5 date_format: 2006-01
 6 list_style: compact
 7 paginate: 30
 8 enabled: true
 9 home:
10 featured_posts: 5
11 pinned_posts_position: top
12 recent_posts: 10
13 list_cols_lg: 3
14 list_cols_md: 2
15 list_style: regular
16 post_date_format: '2006-01-02'
17 post_thumbnail_height: 160px

hugo.json

 1{
 2 "params": {
 3 "hb": {
 4 "blog": {
 5 "archives": {
 6 "date_format": "2006-01",
 7 "list_style": "compact",
 8 "paginate": 30
 9 },
10 "enabled": true,
11 "home": {
12 "featured_posts": 5,
13 "pinned_posts_position": "top",
14 "recent_posts": 10
15 },
16 "list_cols_lg": 3,
17 "list_cols_md": 2,
18 "list_style": "regular",
19 "post_date_format": "2006-01-02",
20 "post_thumbnail_height": "160px"
21 }
22 }
23 }
24}

hugo.toml

 1[params]
 2 [params.hb]
 3 [params.hb.blog]
 4 [params.hb.blog.sidebar]
 5 enabled = true
 6 max_width = '320px'
 7 position = 'start'
 8 sticky = true
 9 width = 0.35
10 [params.hb.blog.sidebar.posts]
11 featured_count = 3
12 fill = true
13 list_style = 'slide'
14 recent_count = 5
15 sections = ['blog', 'posts']
16 style = 'pills'
17 [params.hb.blog.sidebar.profile]
18 avatar = '/images/avatar.png'
19 avatar_size = 100
20 company = 'Your Company'
21 description = 'Welcome to my blog'
22 location = 'Your Location'
23 title = 'Site Author'
24 [params.hb.blog.sidebar.profile.socials]
25 _color = 'primary'
26 email = 'mailto:your@email.com'
27 github = 'yourusername'
28 linkedin = 'yourprofile'
29 twitter = 'yourusername'
30 [params.hb.blog.sidebar.taxonomies]
31 authors = true
32 categories = true
33 count_threshold = 1
34 series = true
35 tags = true

hugo.yaml

 1params:
 2 hb:
 3 blog:
 4 sidebar:
 5 enabled: true
 6 max_width: 320px
 7 position: start
 8 posts:
 9 featured_count: 3
10 fill: true
11 list_style: slide
12 recent_count: 5
13 sections:
14 - blog
15 - posts
16 style: pills
17 profile:
18 avatar: /images/avatar.png
19 avatar_size: 100
20 company: Your Company
21 description: Welcome to my blog
22 location: Your Location
23 socials:
24 _color: primary
25 email: mailto:your@email.com
26 github: yourusername
27 linkedin: yourprofile
28 twitter: yourusername
29 title: Site Author
30 sticky: true
31 taxonomies:
32 authors: true
33 categories: true
34 count_threshold: 1
35 series: true
36 tags: true
37 width: 0.35

hugo.json

 1{
 2 "params": {
 3 "hb": {
 4 "blog": {
 5 "sidebar": {
 6 "enabled": true,
 7 "max_width": "320px",
 8 "position": "start",
 9 "posts": {
10 "featured_count": 3,
11 "fill": true,
12 "list_style": "slide",
13 "recent_count": 5,
14 "sections": [
15 "blog",
16 "posts"
17 ],
18 "style": "pills"
19 },
20 "profile": {
21 "avatar": "/images/avatar.png",
22 "avatar_size": 100,
23 "company": "Your Company",
24 "description": "Welcome to my blog",
25 "location": "Your Location",
26 "socials": {
27 "_color": "primary",
28 "email": "mailto:your@email.com",
29 "github": "yourusername",
30 "linkedin": "yourprofile",
31 "twitter": "yourusername"
32 },
33 "title": "Site Author"
34 },
35 "sticky": true,
36 "taxonomies": {
37 "authors": true,
38 "categories": true,
39 "count_threshold": 1,
40 "series": true,
41 "tags": true
42 },
43 "width": 0.35
44 }
45 }
46 }
47 }
48}

Comment System Configuration

Choose one or combine multiple comment systems:

hugo.toml

 1[params]
 2 [params.hb]
 3 [params.hb.blog]
 4 [params.hb.blog.disqus]
 5 shortname = 'your-disqus-shortname'
 6 [params.hb.blog.giscus]
 7 category = 'General'
 8 category_id = 'your-category-id'
 9 mapping = 'pathname'
10 repo = 'username/repository'
11 repo_id = 'your-repo-id'
12 theme = 'preferred_color_scheme'
13 [params.hb.blog.twikoo]
14 env_id = 'your-twikoo-env-id'
15 region = 'ap-guangzhou'
16 [params.hb.blog.utterances]
17 issue_term = 'pathname'
18 repo = 'username/repository'
19 theme = 'preferred-color-scheme'

hugo.yaml

 1params:
 2 hb:
 3 blog:
 4 disqus:
 5 shortname: your-disqus-shortname
 6 giscus:
 7 category: General
 8 category_id: your-category-id
 9 mapping: pathname
10 repo: username/repository
11 repo_id: your-repo-id
12 theme: preferred_color_scheme
13 twikoo:
14 env_id: your-twikoo-env-id
15 region: ap-guangzhou
16 utterances:
17 issue_term: pathname
18 repo: username/repository
19 theme: preferred-color-scheme

hugo.json

 1{
 2 "params": {
 3 "hb": {
 4 "blog": {
 5 "disqus": {
 6 "shortname": "your-disqus-shortname"
 7 },
 8 "giscus": {
 9 "category": "General",
10 "category_id": "your-category-id",
11 "mapping": "pathname",
12 "repo": "username/repository",
13 "repo_id": "your-repo-id",
14 "theme": "preferred_color_scheme"
15 },
16 "twikoo": {
17 "env_id": "your-twikoo-env-id",
18 "region": "ap-guangzhou"
19 },
20 "utterances": {
21 "issue_term": "pathname",
22 "repo": "username/repository",
23 "theme": "preferred-color-scheme"
24 }
25 }
26 }
27 }
28}

hugo.toml

 1[params]
 2 [params.hb]
 3 [params.hb.blog]
 4 [params.hb.blog.social_share_buttons]
 5 [params.hb.blog.social_share_buttons.media]
 6 email = true
 7 facebook = true
 8 linkedin = true
 9 pinterest = true
10 reddit = true
11 telegram = true
12 twitter = true
13 whatsapp = true

hugo.yaml

 1params:
 2 hb:
 3 blog:
 4 social_share_buttons:
 5 media:
 6 email: true
 7 facebook: true
 8 linkedin: true
 9 pinterest: true
10 reddit: true
11 telegram: true
12 twitter: true
13 whatsapp: true

hugo.json

 1{
 2 "params": {
 3 "hb": {
 4 "blog": {
 5 "social_share_buttons": {
 6 "media": {
 7 "email": true,
 8 "facebook": true,
 9 "linkedin": true,
10 "pinterest": true,
11 "reddit": true,
12 "telegram": true,
13 "twitter": true,
14 "whatsapp": true
15 }
16 }
17 }
18 }
19 }
20}

1[params.hb.blog.related_posts]
2 number = 6 # Number of related posts to show
3 list_style = "slide" # Options: slide, vertical

Page-Level Configuration

Blog Post Front Matter

 1
 2---
 3title: 'Your Blog Post Title'
 4date: 2025-01-03T10:00:00Z
 5draft: false
 6
 7# Content Organization
 8description: 'SEO-friendly description'
 9featured: true # Mark as featured post
10pinned: false # Pin to top of listing
11series: ['Tutorial'] # Group into series
12categories: ['Tech'] # Post categories
13tags: ['Hugo', 'Blog'] # Post tags
14authors: ['john-doe'] # Multiple authors supported
15
16# Page Behavior
17comments: true # Enable comments (default: true)
18sidebar: true # Show sidebar (default: true)
19toc: true # Show table of contents
20noindex: false # SEO indexing control
21
22# Social and Sharing
23images: ['/images/featured.png'] # Featured image for social sharing
24
25# Custom Parameters
26weight: 10 # Manual ordering
27nav_weight: 100 # Navigation weight
28---

Layout Styles and Display Options

List Layout Styles

Regular Layout (list_style = "regular")
- Card-based layout with images, titles, and summaries
- Responsive grid system (2 cols on medium, 3 cols on large screens)
- Best for general-purpose blogs
Minimalist Layout (list_style = "minimalist")
- Clean, text-focused design
- Compact post previews with metadata
- Ideal for text-heavy content
Cascade Layout (list_style = "cascade")
- Pinterest-style masonry grid
- Auto-adjusting heights based on content
- Great for mixed content types

Practical Configuration Examples

Complete Blog Setup Example

Here’s a comprehensive example configuration file (config/_default/params.yaml):

 1# HBStack Blog Module Configuration
 2hb:
 3 blog:
 4 # Core settings
 5 enabled: true
 6 post_thumbnail_height: 180px
 7 post_thumbnail_resize_height: 360
 8 post_thumbnail_default: images/thumbnail.png
 9 post_read_more: true
10 paginate: 12
11 post_thumbnail_placeholder: 'Blog'
12 post_thumbnail: true
13 list_cols_lg: 3
14 post_date_format: ':date_long'
15
16 # Homepage settings
17 home:
18 taxonomies: true
19 featured_posts: 5
20 main_sections:
21 - blog
22 - posts
23 - tutorials
24
25 # Sidebar configuration
26 sidebar:
27 enabled: true
28 position: start
29 width: 0.35
30 max_width: 320px
31 sticky: true
32
33 # Profile widget
34 profile:
35 avatar: /images/avatar.png
36 avatar_size: 200
37 title: 'Personal Blog'
38 description: 'Welcome to my tech blog'
39 company: '[Your Company](https://example.com)'
40 location: 'Internet'
41 socials:
42 github: yourusername
43 twitter: yourusername
44 linkedin: yourprofile
45
46 # Posts widget
47 posts:
48 style: pills
49 list_style: slide
50 recent_count: 10
51 featured_count: 5
52
53 # Taxonomies widget
54 taxonomies:
55 style: pills
56 count: true
57 limit: 10
58
59 # Comment system (choose one)
60 giscus:
61 repo: username/repository
62 repo_id: R_kgDOJP3qtA
63 category_id: DIC_kwDOJP3qtM4CVavM
64
65 # Social sharing
66 social_share_buttons:
67 media:
68 twitter: true
69 linkedin: true
70 facebook: true
71 reddit: true
72 email: true

Blog Section Setup

Create content/blog/_index.md:

 1---
 2title: Blog
 3menu:
 4 main:
 5 identifier: blog
 6 weight: 3
 7 params:
 8 icon:
 9 vendor: fas
10 name: blog
11 color: primary
12 description: 'Latest blog posts and tutorials'
13---
14Welcome to my blog where I share insights about technology, programming, and web development.

Featured Post Example

Create content/blog/my-first-post/index.md:

 1---
 2title: "Getting Started with HBStack Blog"
 3date: 2025-01-03T10:00:00Z
 4draft: false
 5featured: true
 6pinned: true
 7description: "Learn how to set up and configure the HBStack blog module"
 8
 9# Organization
10series: ["HBStack Guide"]
11categories: ["Web Development"]
12tags: ["Hugo", "HBStack", "Blog"]
13authors: ["your-username"]
14
15# SEO and Social
16images: ["/images/blog/hbstack-intro.png"]
17noindex: false
18
19# Page features
20comments: true
21sidebar: true
22toc: true
23---
24
25This post will guide you through setting up the HBStack blog module...
26
27
28
29
30
31## Introduction
32
33The HBStack blog module provides...

Advanced Features

Multi-Author Support

Create author pages in content/authors/:

 1# content/authors/john-doe/_index.md
 2---
 3title: 'John Doe'
 4description: 'Senior Developer and Tech Writer'
 5images: ['/images/authors/john-doe.jpg']
 6socials:
 7 github: johndoe
 8 twitter: johndoe
 9 linkedin: johndoe
10 website: https://johndoe.dev
11---
12John is a senior developer with 10 years of experience...

Reference authors in posts:

1---
2title: 'Collaborative Post'
3authors: ['john-doe', 'jane-smith']
4---

Series and Collections

Organize related posts into series:

Blog Module on Ghafoor's Personal Blog

Blog Module Configuration Guide

Blog Module Architecture

Core Components

Available Blog Sub-Modules

Global Blog Configuration

Core Site Parameters

Sidebar Configuration

Comment System Configuration

Page-Level Configuration

Blog Post Front Matter

Layout Styles and Display Options

List Layout Styles

Practical Configuration Examples

Complete Blog Setup Example

Blog Section Setup

Featured Post Example

Advanced Features

Multi-Author Support

Series and Collections

Blog Module on Ghafoor's Personal Blog

Blog Module Configuration Guide

Blog Module Architecture

Core Components

Available Blog Sub-Modules

Global Blog Configuration

Core Site Parameters

Sidebar Configuration

Comment System Configuration

Social Sharing Configuration

Related Posts Configuration

Page-Level Configuration

Blog Post Front Matter

Layout Styles and Display Options

List Layout Styles

Practical Configuration Examples

Complete Blog Setup Example

Blog Section Setup

Featured Post Example

Advanced Features

Multi-Author Support

Series and Collections