Configuration on Ghafoor's Personal Blog

Configuration Support & Module Organization

noreply@example.com (AG Sayyed) — Thu, 25 Sep 2025 14:30:00 +0000

Configuration Support & Module Organization

This document details how we successfully achieved modular configuration organization for HBStack without breaking Hugo’s core functionality. We solved the challenge of separating module-specific configurations while maintaining proper site rendering and avoiding unintended multilingual site creation.

🎯 The Challenge

Initially, we attempted to separate HBStack module configurations into individual files to improve maintainability:

params.blog.yaml - Blog module configuration
params.docs.yaml - Documentation module configuration
params.pwa.yaml - PWA module configuration
params.seo.yaml - SEO module configuration

Problem: Hugo interpreted these as language-specific configurations, creating separate language sites instead of module configurations, resulting in:

Config Map and Secrets

noreply@example.com (AG Sayyed) — Fri, 18 Jul 2025 10:08:42 +0000

This document explains how Kubernetes ConfigMaps and Secrets enable separation of configuration and sensitive data from application code. It covers their characteristics, creation methods, and best practices for securely managing environment variables and application settings in containerized deployments.

Introduction to ConfigMaps and Secrets

Kubernetes ConfigMaps and Secrets are API objects designed to decouple configuration and sensitive data from application code. ConfigMaps store non-confidential key-value pairs, while Secrets are intended for sensitive information and provide encoding for security.

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.

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:

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.

Configuration on Ghafoor's Personal Blog

Configuration Support & Module Organization

Configuration Support & Module Organization

🎯 The Challenge

Config Map and Secrets

Introduction to ConfigMaps and Secrets

Necessary Changes

Modifying the package.json File

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

Project Local Configuration

Project Configuration for Formatting and Linting

EditorConfig (.editorconfig)