HBStack on Ghafoor's Personal Blog

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:

Footer Module

noreply@example.com (AG Sayyed) — Sat, 16 May 2026 00:00:00 +0000

The footer module provides a universal footer section for HBStack sites, featuring configurable menus, social media links, copyright notices, and extensible hooks for custom content injection. It is the ideal location for placing donation buttons, affiliate disclaimers, newsletter signup links, and other monetization-related elements.

Overview

The footer module is a core component of the HBStack framework, automatically included when using the meta/recommended module set. It ships with built-in support for multi-level menus, social link generation, and several extension points via HugoPress hooks.

Taxonomies in HBStack

noreply@example.com (AG Sayyed) — Wed, 01 Oct 2025 09:16:26 +0000

Summary content goes here.

What are Taxonomies?

Taxonomies are a way to group and classify content in Hugo. They help organize your site by categorizing content into meaningful groups, making it easier for users to navigate and find related information. Common taxonomies include categories and tags.

Why use Taxonomies in HBStack?

Using taxonomies in HBStack enhances the user experience by providing structured navigation and improving content discoverability. They allow you to create dynamic lists of related content, which can increase user engagement and time spent on your site.

HBStack & HugoMods Shortcodes Showcase

noreply@example.com (AG Sayyed) — Mon, 07 Jul 2025 15:00:00 +0000

A comprehensive showcase of all available shortcodes in HBStack and HugoMods frameworks, including Bootstrap components, extended media shortcodes, and modular features with examples and module import requirements.

1. Module Requirements

Before using these shortcodes, ensure you have the following modules imported in your config/_default/module.yaml:

 1imports:
 2 # Custom modules
 3 - path: github.com/agsayyed/ags-mcq
 4 - path: github.com/agsayyed/ags-markmap
 5 # gallery modules.
 6 - path: github.com/hbstack/gallery
 7 - path: github.com/hbstack/gallery/modules/breadcrumb
 8 - path: github.com/hbstack/syntax-highlighting/styles/github-dark
 9 - path: github.com/hugomods/shortcodes
10 - path: github.com/hbstack/shortcodes
11
12 # Bootstrap components for shortcodes
13 - path: github.com/hugomods/bootstrap
14 - path: github.com/hbstack/bootstrap
15 - path: github.com/gohugoio/hugo-mod-bootstrap-scss/v5
16
17 # Additional shortcode modules
18 - path: github.com/hugomods/encrypt
19 - path: github.com/hugomods/katex
20 - path: github.com/hugomods/mermaid
21 - path: github.com/hugomods/video-js
22 - path: github.com/hugomods/kroki
23 - path: github.com/hugomods/echarts
24
25 # Core modules
26 - path: github.com/hugomods/hugopress
27 # syntax highlighting, see https://hbstack.dev/en/docs/modules/syntax-highlighting/.
28
29 # icons modules
30 - path: github.com/hugomods/icons/vendors/font-awesome
31 - path: github.com/hugomods/icons/vendors/bootstrap
32 # - path: github.com/hugomods/icons/vendors/mdi
33 # - path: github.com/hugomods/icons/vendors/simple-icons
34 # - path: github.com/hugomods/icons/vendors/tabler
35 # - path: github.com/hugomods/icons/vendors/feather
36
37 # header themes
38 - path: github.com/hbstack/header/themes/pills
39 # - path: github.com/hbstack/header/themes/tabs
40 # - path: github.com/hbstack/header/themes/classic
41
42 # blog sidebar
43 - path: github.com/hbstack/blog/modules/sidebar/profile
44 - path: github.com/hbstack/blog/modules/sidebar/posts
45 - path: github.com/hbstack/blog/modules/sidebar/taxonomies
46
47 # blog comments engine
48 - path: github.com/hbstack/blog/modules/giscus
49 # - path: github.com/hbstack/blog/modules/disqus
50 # - path: github.com/hbstack/blog/modules/utterances
51
52 # blog table of contents scrollspy
53 - path: github.com/hbstack/blog/modules/toc-scrollspy
54
55 # blog content panel
56 - path: github.com/hbstack/blog/modules/content-panel
57
58 # docs comments engine
59 - path: github.com/hbstack/docs/modules/giscus
60 # - path: github.com/hbstack/docs/modules/utterances
61 # - path: github.com/hbstack/docs/modules/disqus
62
63 # docs table of contents scrollspy
64 - path: github.com/hbstack/docs/modules/toc-scrollspy
65
66 # docs content panel
67 - path: github.com/hbstack/docs/modules/content-panel
68
69 # other modules
70 # - path: github.com/hugomods/google-analytics
71 # - path: github.com/hugomods/google-adsense
72
73 # recommended modules
74 # check which modules were imported by recommended module by "hugo mod graph | grep recommended".
75 # see also https://hbstack.dev/en/docs/modules/meta/.
76 # to remove unused modules, you need to replace the recommended module with modules your need.
77 # see also https://hbstack.dev/en/2023/10/replace-meta-modules/.
78 - path: github.com/hbstack/meta/recommended

2. Bootstrap UI Components

2.1. Alert Messages

Module Required: github.com/hugomods/bootstrap

Basic Useful Hugo Commands

noreply@example.com (AG Sayyed) — Mon, 07 Jul 2025 10:52:27 +0000

Essential Hugo commands for development, building, and managing your HBStack-powered site including server commands, build options, and debugging utilities.

Hugo Commands

Content for Hugo commands will be added here.

FAQs

Dealing with Server Commands

noreply@example.com (AG Sayyed) — Mon, 07 Jul 2025 10:52:27 +0000

This document provides the information about running and managing Hugo server

🧩 Managing Multiple Site Processes on a Single Machine

When running multiple Hugo sites or similar services on one machine, it’s essential to monitor and manage active processes to avoid port conflicts, memory leaks, or zombie jobs.

🔍 Finding Running Jobs

Use ps and grep to locate processes:

1ps aux | grep hugo | grep -v grep

This lists all Hugo-related processes. Example output:

Running Hugo Server

noreply@example.com (AG Sayyed) — Mon, 07 Jul 2025 10:52:27 +0000

Essential Hugo commands for development, building, and managing your HBStack-powered site including server commands, build options, and debugging utilities.

Running Hugo Server

To start the Hugo development server, use the following command:

1hugo server

This command will start the server and watch for changes in your content files, automatically rebuilding the site as you make edits.

When a server is run while you want to build your site, you can use different configuration options. Learning about them always helps optimize your workflow. What commands are available can be seen from hugo help. Every command has its own set of flags and options that can be used to customize its behavior.

JavaScript & Shortcodes in HBStack

noreply@example.com (AG Sayyed) — Sun, 08 Jun 2025 09:45:12 +0000

This guide provides practical, working examples of JavaScript implementation in HBStack. From a simple Hello World demonstration to advanced integration patterns, you'll see exactly how to build interactive features using Hugo shortcodes and the HBStack framework.

Practical Example: Hello World Script

Let’s start with a simple example to demonstrate how custom JavaScript works in HBStack. Below is a live demonstration of a basic JavaScript file being loaded using Hugo shortcodes.

How to use JavaScript and Styles in HBStack

noreply@example.com (AG Sayyed) — Thu, 05 Jun 2025 13:19:20 +0000

A comprehensive guide on how to use JavaScript and custom scripts in the HBStack framework, covering the assets folder structure, custom script implementation, and when to use the assets/hb folder structure.

Work Flow

noreply@example.com (AG Sayyed) — Tue, 15 Apr 2025 17:37:37 +0000

Steps to Follow

This is necessary for understanding the processes involved in the workflow.

Source the script file so that the functions are available in your current shell session:
```
1source ./scripts/env-helper.sh
```
Use the following commands to carry out the tasks:

1hugo-dev
2hugo-prod
3hugo-staging
4hugo-build-prod
5hugo-build-staging
6hugo-env
7hugo-stop
8hugo-cleanup

FAQs

Docker Environment Setups

noreply@example.com (AG Sayyed) — Tue, 15 Apr 2025 13:43:00 +0000

This document explains how to use the environment configuration setup for different deployment scenarios including development, production, and staging environments.

Hugo Environment Setup

This document explains how to use the environment configuration setup for different deployment scenarios.

Environment Structure

We’ve organized environment configurations into separate files in the env directory:

env/.env.development - Development environment settings
env/.env.production - Production environment settings
env/.env.staging - Staging environment settings

Installation

To set up the environment structure, run:

Necessary Changes

noreply@example.com (AG Sayyed) — Tue, 15 Apr 2025 10:40:31 +0000

This document outlines the necessary changes to the `package.json` file when starting a new project based on HBStack. It includes details on updating project metadata, repository links, and other essential configurations.

Modifying the package.json File

The package.json file contains critical metadata about your project, including its name, repository URL, and other identifying information. When starting a new project based on HBStack, you should update this file to reflect your own project’s details.

Header Navigation

noreply@example.com (AG Sayyed) — Mon, 14 Apr 2025 15:12:15 +0000

Advanced techniques and workflows for working with HBStack, including optimization strategies, debugging tips, and productivity enhancements.

The header by defualt is not shown unless a layout is used that is designed to show it. The header contains the following elements:
- Logo ( A Site logo)
- Title ( The title of the site)
- Navigation links ( Links to different sections of the site)
  - These links are present in Menus
- Social media icons ( Links to social media profiles)
- Search bar ( A search input field)

Header Settings

The header settings can be configured in eihter the hugo.ymal of params.yaml file.
The following are few settings:

 1hb:
 2 header:
 3 brand: PN # the brand name, leave it empty to use site's title.
 4 logo_bg: '#712cf9' # logo background color, used by logo with transparent background.
 5 # see https://hbstack.dev/en/docs/modules/socials/.
 6 socials:
 7 github: hbstack
 8 # twitter: razonyang
 9 rss: true
10 mastodon: https://techhub.social/@hbstack
11 footer:
12 # see https://hbstack.dev/en/docs/modules/socials/.
13 socials:
14 _color: true # when false, remove the color of social icons.
15 github: hbstack
16 twitter: razonyang
17 rss: true
18 mastodon: https://techhub.social/@hbstack

FAQs

Home Page

noreply@example.com (AG Sayyed) — Mon, 14 Apr 2025 15:03:22 +0000

Learn how to work effectively with HBStack, including development workflows, best practices, and common tasks for building and maintaining your site.

Home page

Hbstack does not have any built in home page which would appear at development localhost:1313 or any other port which would appear at / endpoints.
A blank area is shown under ports:9000/ in the pricture shown below.

It is to be defined by the settings. By convention the _index.md under content folder is the best choice.

1---
2title: Projects Notes
3layout: landing
4#description: Personal project tracking and documentation
5---

The above frontmatter setting is an example of how to set up a home page in HBStack. It uses the landing layout, which is suitable for a home page.
The title and description fields can be customized to reflect the purpose of your home page.
The home page can include links to various sections of your site, such as project documentation, notes, and other resources.

Important

Site Configuration

noreply@example.com (AG Sayyed) — Sun, 13 Apr 2025 21:13:46 +0000

A comprehensive guide to configuring your HBStack-based Hugo site. Learn to set up hugo.yaml, manage parameters, and optimize site settings for production.

Understanding the Hugo Configuration File

The primary configuration for your HBStack site is managed through the config/_default/hugo.yaml file. This file contains essential settings that control how your site functions, its appearance, and various technical aspects of Hugo’s behavior.

Basic Site Settings

1baseURL: https://theme.hbstack.dev/
2title: HB Starter Theme Template
3copyright: 'Copyright © 2022-{year} [Hugo Modules](https://hugomods.com/) and [HB Framework](https://hbstack.dev/). All Rights Reserved.'

baseURL: This is the root URL where your site will be published. Change this to your domain (e.g., https://yourdomain.com/).
title: The name of your site that appears in the browser tab and is used throughout the site. Customize this to your project name.
copyright: The copyright notice shown in the footer. Note the {year} placeholder is automatically replaced with the current year.

Changed Settings for the Project

1baseURL: https://agsayyed.github.io/hugo-with-docker/
2title: Hugo With Docker
3# Copyright, the {year} is the placeholder of this year.
4copyright: 'Copyright © 2024-{year} AG Sayyed. All Rights Reserved.'

Language Settings

1defaultContentLanguage: en
2defaultContentLanguageInSubdir: true

defaultContentLanguage: Sets the default language for your site (currently “en” for English).
defaultContentLanguageInSubdir: When set to true, adds the language code to URLs (e.g., /en/docs/). Set to false to remove language codes from URLs.

Site Features and Behavior

1enableRobotsTXT: true
2timeout: 120s
3enableEmoji: true
4
5title_sections: true
6title_sections_depth: 0
7title_sections_depth_dir: end

enableRobotsTXT: Generates a robots.txt file for search engine crawlers.
timeout: Sets the build timeout (120 seconds) - useful for sites with complex image processing.
enableEmoji: Allows emoji shortcodes in your content (e.g., :smile: → 😄).
title_sections: Controls whether section names appear in page titles.
title_sections_depth and title_sections_depth_dir: Control how deep section names go in titles.

URL Structure

1permalinks:
2 blog: /blog/:year/:month/:title

permalinks: Defines URL patterns for different content types. Modify this section to customize URL structures for your content.

Output Formats

1outputs:
2 home:
3 - HTML
4 - Offline
5 - RSS
6 - SearchIndex
7 - WebAppManifest

This section defines what output formats are generated. The current configuration supports:
- Standard HTML pages
- Offline pages (for PWA support)
- RSS feeds
- Search index (for site search functionality)
- Web App Manifest (for PWA installation)

Taxonomy Configuration

1taxonomies:
2 authors: authors
3 tags: tags
4 categories: categories
5 series: series

taxonomies: Defines how content is categorized. You can modify this section to add, remove, or rename taxonomies according to your organizational needs.

Build Settings

1build:
2 writeStats: true

writeStats: Required for PurgeCSS to optimize CSS files. Leave this enabled for better performance.

Markdown Rendering

1markup:
2 goldmark:
3 renderer:
4 unsafe: true
5 highlight:
6 noClasses: false
7 lineNos: true
8 lineNumbersInTable: false

goldmark.renderer.unsafe: When set to true, allows raw HTML in Markdown files.
highlight: Controls code syntax highlighting:
- noClasses: When false, uses CSS classes for styling.
- lineNos: Enables line numbers in code blocks.
- lineNumbersInTable: When false, shows line numbers inline rather than in a table format.

 1related:
 2 includeNewer: true
 3 indices:
 4 - name: keywords
 5 weight: 100
 6 - name: tags
 7 weight: 80
 8 # Additional indices...
 9 threshold: 10
10 toLower: false

This section controls how related content suggestions work:
- includeNewer: When true, newer posts can be suggested as related to older ones.
- indices: Lists factors for determining relatedness, with higher weights having more influence.
- threshold: Minimum score needed to include a page in related content.

Security Settings

1security:
2 funcs:
3 getenv:
4 - ^HUGO
5 - CI$
6 - PWD

Controls which environment variables can be accessed by Hugo templates for security purposes.

Development Environment Configuration

Hugo allows for environment-specific configuration using separate files. For local development, the project uses a specific configuration located at config/development/hugo.yaml:

Pruning Your HBStack Project

noreply@example.com (AG Sayyed) — Sun, 13 Apr 2025 10:01:22 +0000

After setting up your HBStack project and ensuring it works correctly, the next step is to prune unnecessary files and configurations to keep your project clean, reduce its size, and make it easier to maintain.

Overview

Pruning involves removing language files you don’t need, example content, unused module configurations, and updating various configuration files to match your project requirements.

Removing Unnecessary Files

HBStack supports multiple languages through its i18n system. If you only need specific languages, you can remove the others:

Cloning and Keeping Track of Changes

noreply@example.com (AG Sayyed) — Sun, 13 Apr 2025 06:29:16 +0000

Instructions for setting up the project and keeping track of changes in the original repository. This guide covers cloning, Docker setup, and Git workflow management.

Setting Up the Project

Prerequisites

Install Required Tools:
- Docker: Ensure Docker is installed and running on your system.
- Hugo: Install Hugo for local development.
- Git: Ensure Git is installed for version control.

Clone the Repository:

1git clone https://github.com/<upstream-repo-owner>/hbstack.git my-hbstack-project
2cd my-hbstack-project

Initialize Your Own Repository:

Docker Setup

noreply@example.com (AG Sayyed) — Sat, 12 Apr 2025 09:50:11 +0000

Complete guide to setting up Hugo with Docker for your HBStack site. Covers Docker installation, configuration, and containerized development workflows.

Using Docker with Hugo simplifies development by providing a consistent environment across different systems.

Project Local Configuration

noreply@example.com (AG Sayyed) — Sat, 12 Apr 2025 09:06:46 +0000

A comprehensive guide to setting up HBStack project configuration including EditorConfig, linting, and markdown handling for code quality and consistency.

Project Configuration for Formatting and Linting

This project implements a comprehensive approach to code formatting, linting, and markdown handling. Below is a detailed explanation of how these components work together to maintain code quality and consistency.

EditorConfig (.editorconfig)

The .editorconfig file provides basic code style definitions that work across different editors and IDEs.

Setup HBStack Guide

noreply@example.com (AG Sayyed) — Sat, 12 Apr 2025 09:06:46 +0000

A comprehensive guide to setting up HBStack with Docker. This guide covers framework understanding, command execution patterns, and development workflow setup.

Understanding HBStack Framework

HBStack is a modular Hugo theme framework built on top of Hugo’s module system, Bootstrap, and other modern web technologies.

Docker vs. Non-Docker Command Execution

When working with HBStack, commands can be managed differently depending on whether you’re using Docker or not.

Standard npm Scripts (Non-Docker)

In a traditional setup without Docker, HBStack commands are defined in package.json:

HBStack 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

Footer Module

Overview

Taxonomies in HBStack

What are Taxonomies?

Why use Taxonomies in HBStack?

HBStack & HugoMods Shortcodes Showcase

1. Module Requirements

2. Bootstrap UI Components

2.1. Alert Messages

Basic Useful Hugo Commands

Hugo Commands

FAQs

Dealing with Server Commands

🧩 Managing Multiple Site Processes on a Single Machine

🔍 Finding Running Jobs

Running Hugo Server

Running Hugo Server

JavaScript & Shortcodes in HBStack

Practical Example: Hello World Script

How to use JavaScript and Styles in HBStack

Work Flow

Steps to Follow

FAQs

Docker Environment Setups

Hugo Environment Setup

Environment Structure

Installation

Necessary Changes

Modifying the package.json File

Header Navigation

HbStack Header Navigation

Header Settings

FAQs

Home Page

Home page

Site Configuration

Understanding the Hugo Configuration File

Basic Site Settings

Changed Settings for the Project

Language Settings

Site Features and Behavior

URL Structure

Output Formats

Taxonomy Configuration

Build Settings

Markdown Rendering

Related Content Settings

Security Settings

Development Environment Configuration

Pruning Your HBStack Project

Overview

Removing Unnecessary Files

Language-Related Files

Cloning and Keeping Track of Changes

Setting Up the Project

Prerequisites

Docker Setup

Project Local Configuration