A comprehensive guide to configuring your HBStack-based Hugo site. Learn to set up hugo.yaml, manage parameters, and optimize site settings for production.
A comprehensive guide to configuring your HBStack-based Hugo site. Learn to set up hugo.yaml, manage parameters, and optimize site settings for production.
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.
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.'
https://yourdomain.com/).{year} placeholder is automatically replaced with the current year.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.'
1defaultContentLanguage: en
2defaultContentLanguageInSubdir: true
true, adds the language code to URLs (e.g., /en/docs/). Set to false to remove language codes from URLs.1enableRobotsTXT: true
2timeout: 120s
3enableEmoji: true
4
5title_sections: true
6title_sections_depth: 0
7title_sections_depth_dir: end
:smile: → 😄).1permalinks:
2 blog: /blog/:year/:month/:title
1outputs:
2 home:
3 - HTML
4 - Offline
5 - RSS
6 - SearchIndex
7 - WebAppManifest
1taxonomies:
2 authors: authors
3 tags: tags
4 categories: categories
5 series: series
1build:
2 writeStats: true
1markup:
2 goldmark:
3 renderer:
4 unsafe: true
5 highlight:
6 noClasses: false
7 lineNos: true
8 lineNumbersInTable: false
true, allows raw HTML in Markdown files.false, uses CSS classes for styling.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
true, newer posts can be suggested as related to older ones.1security:
2 funcs:
3 getenv:
4 - ^HUGO
5 - CI$
6 - PWD
Hugo allows for environment-specific configuration using separate files. For local development, the project uses a specific configuration located at config/development/hugo.yaml:
1baseURL: http://localhost:1313/
This overrides the production baseURL setting to point to your local development server running on port 1313. When you run the development server with:
1hugo server
Hugo will use this configuration, allowing you to preview your site locally at without affecting the production configuration.
If you need to change the local server port or add other development-specific settings:
config/development/hugo.yaml filebaseURL to match your preferred port (e.g., http://localhost:8080/)This environment-specific configuration approach keeps your development settings separate from production, which is a best practice for web development.
config/_default/hugo.yaml file in your text editor.When starting a new project based on HBStack, these are the most important settings to change:
false if you only have one languageHugo employs a sophisticated configuration system that allows for environment-specific settings while maintaining a core configuration. Understanding how Hugo detects and merges these configurations is essential for effective site management.
Hugo’s configuration follows this hierarchy:
1config/
2├── _default/
3│ └── hugo.yaml # Base configuration for all environments
4└── development/
5 └── hugo.yaml # Development-specific overrides
Default Configuration: Hugo always looks for configuration in the config/_default/ directory first. This serves as the base configuration for all environments.
Environment-Specific Configuration: When Hugo runs with a specific environment (like “development”), it looks for a matching directory with that name in the config folder.
File Format Detection: Hugo supports YAML, TOML, and JSON formats. It automatically detects the file extension (.yaml, .toml, .json) and processes the file accordingly.
When Hugo runs, it performs a smart merge of configurations:
Default Loading: First, all settings from config/_default/hugo.yaml are loaded.
Environment Detection:
hugo server, Hugo automatically uses the “development” environment.hugo (build), Hugo uses the “production” environment.--environment flag (e.g., hugo --environment staging).Merging Process:
config/development/hugo.yaml) override corresponding settings from the default configuration.Command-Line Overrides: Any settings passed via command-line flags take highest precedence and override both default and environment-specific configurations.
In our project:
config/_default/hugo.yaml contains all the base settings for the site, including a production baseURL of https://agsayyed.github.io/hugo-with-docker/.config/development/hugo.yaml contains only baseURL: http://localhost:1313/.When you run hugo server, Hugo:
baseURL setting with the development valueThis allows you to maintain different configurations for different environments without duplicating all settings.
baseURL, theme, and any other settings that should differ from production. 1module:
2 replacements: github.com/agsayyed/ags-mcq -> ../../ags-modules-ags-mcq
3 mounts:
4 - source: 'layouts'
5 target: 'layouts'
6 - source: 'assets/hb/modules/agsayyed'
7 target: 'assets/hb/modules/agsayyed'
8 - source: 'static/sounds' # Ensure this line is correct
9 target: 'static/sounds' # Ensure this line is correct
10# Add module assets configuration
11outputFormats:
12 ags-mcqAssets:
13 baseName: 'ags-mcq'
14 mediaType: 'text/javascript'
15 isPlainText: true
Hugo provides a powerful built-in feature called “Related Content” that allows you to automatically suggest similar content to your readers. This feature is particularly useful for blogs and documentation sites where you want to help users discover related articles.
Hugo uses a sophisticated algorithm to determine relationships between content pages based on front matter parameters like tags, categories, date, or keywords. The system works by:
In your existing hugo.yaml configuration file, have a related content configuration:
1# see https://gohugo.io/content-management/related/#configure-related-content
2related:
3 includeNewer: true
4 indices:
5 - name: keywords
6 weight: 100
7 - name: tags
8 weight: 80
9 - name: categories
10 weight: 60
11 - name: series
12 weight: 60
13 - name: authors
14 weight: 10
15 - name: date
16 weight: 10
17 threshold: 10 # for testing, increase it to suit your case.
18 toLower: false
Let’s break down what each of these settings does:
includeNewer: When set to true, Hugo will include pages published after the current page as related content. If set to false, only older content would be considered related.
indices: This defines which front matter parameters Hugo should use to determine relationships and how much weight to give each parameter:
keywords (weight 100): Gives highest priority to matching keywordstags (weight 80): Matching tags are the second most important factorcategories (weight 60): Pages in the same categories are considered relatedseries (weight 60): Pages that are part of the same seriesauthors (weight 10): Content by the same author is loosely relateddate (weight 10): Content with similar publication datesthreshold: This is the minimum score needed for content to be considered related. In your case, it’s set to 10, which is quite low. This means Hugo will be more liberal in suggesting related content. For stricter matching, you could increase this value.
toLower: When set to false, matching is case-sensitive. If set to true, all terms would be converted to lowercase before comparison.
The default configuration is quite comprehensive, but you could enhance it further with:
You could index content headings by adding a “fragments” type index:
1indices:
2 - name: fragmentrefs
3 type: fragments
4 weight: 80
You can create custom indices based on any front matter parameter. For example, if you had a “technology” parameter in your content:
1indices:
2 - name: technology
3 weight: 90
To display related content in your templates, you would use code like this:
1{{ $related := .Site.RegularPages.Related . | first 5 }}
2{{ with $related }}
3 <h3>Related Posts</h3>
4 <ul>
5 {{ range . }}
6 <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
7 {{ end }}
8 </ul>
9{{ end }}
For more advanced use cases, you can specify which indices to search and provide specific values to look for:
1{{ $opts := dict
2 "indices" (slice "tags" "keywords")
3 "document" .
4}}
5
6{{ $related := .Site.RegularPages.Related $opts | first 5 }}
Adjust weights based on your content structure: If your site heavily relies on tags, give tags a higher weight.
Test different threshold values: Start with a lower value and increase it if you get too many unrelated suggestions.
Make sure your content has consistent front matter: The related content feature works best when pages have consistent metadata.
Add related content section at the end of pages: This is where users are most likely to look for additional content.
The configuration you already have is well-balanced for most sites, but you can always fine-tune it based on your specific content structure and user needs.
The hugo.yaml configuration file provides a powerful way to customize your HBStack site. By understanding and modifying these settings, you can tailor your site to meet your specific requirements while maintaining the benefits of the HBStack framework.