Home Page

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

it is the layout template defined in your website or a theme or a framework which renders the contents if there are any.

• The _index.md file shown below will not be rendered as a home page, because it does not have the layout: set.

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

Caution

No Layouts template no Contents, Hbstack is built upon Hugo, and Hugo requires a layout to render the contents.

• In order for the contents to appear any where in the site, there has to be a file that renders the contents. These files are places under the layouts folder.
• The layouts folder contains templates that define how the content is displayed. The convention is to have a _default folder under layouts which contains the single.html and list.html files and may be other files as well.
• When layout field is not set to landing or not defined to point to any other layout, no contents will be rendered on the home page unless it is defined by the type field in the front matter of the _index.md file.
• If the type or layout is not set, the page or a home page either will not be rendered or will be rendered according to section where it is placed.
• For example, if the _index.md file is placed under content/docs/, it will be rendered as a documentation page using the docs layout, and if it is placed under content/blog/, it will be rendered as a blog page.
• In Hbstack, these layouts templates are not visible under the layouts folder or the user who is importing the modules but remains in the cache.
• The cache folder is where the templates are stored after they are compiled by Hugo. This is done to improve performance and reduce the size of the final site.

Header and Footer

• Hbstack comes with a default header and footer which can be shown or hidden. The settings are controlled either in the config.yaml file or in the param.yaml file.
• If the settings are present, the header and footer will be displayed on the home page and other pages for the only one reasons that the layout is set to landing. And by default the header and footer are shown.

Note

Following picture shows the header and footer on the home page with the landing layout. The same layout will be used if you set the layout to be list instead of landing.

Understanding the type Frontmatter Variable

The type frontmatter variable is a fundamental concept in Hugo that controls template selection and content organization. Here’s a comprehensive explanation based on Hugo’s documentation and HBStack usage patterns:

What is type in Hugo?

According to Hugo’s official documentation, the type variable determines which template directory Hugo looks in when rendering a page. From the Hugo Template Lookup Order documentation:

Type Is value of type if set in front matter, else it is the name of the root section (e.g. “blog”). It will always have a value, so if not set, the value is “page”.

How type Works

1. Explicit Setting: When you set type: docs in frontmatter, Hugo looks for templates in /layouts/docs/
2. Automatic Detection: If no type is specified, Hugo uses the top-level directory name (e.g., content in /content/blog/ gets type: blog)
3. Fallback: For content in the root /content/ directory, the default type is page

HBStack-Specific Types

Based on exploration of your Hugo modules cache, HBStack provides these specific content types:

1. type: blog

• Templates: /layouts/blog/single.html, /layouts/blog/list.html
• Module: hbstack/blog@v0.42.1
• Features: Post metadata, pagination, comments, related posts, categories/tags
• Usage: Individual blog posts and blog section pages

2. type: docs

• Templates: /layouts/docs/single.html, /layouts/docs/list.html
• Module: hbstack/docs@v0.24.0
• Features: Sidebar navigation, table of contents, breadcrumbs, search
• Usage: Documentation pages and doc sections

3. type: gallery

• Templates: /layouts/gallery/single.html, /layouts/gallery/list.html
• Module: hbstack/gallery@v0.13.1
• Features: Image grid, lightbox, album metadata, pagination
• Usage: Photo albums and gallery sections

4. type: archives

• Templates: /layouts/archives/
• Module: Found in blog module
• Features: Date-based post archives
• Usage: Archive listing pages

5. type: authors

• Templates: /layouts/authors/
• Module: Found in blog module
• Features: Author profiles and post listings
• Usage: Author biography and post listing pages

Available Types in this Site

The type template is usually present in archetype files, my site has these types available:

1/archetypes/blog.md        # type: blog (auto-detected)
2/archetypes/docs.md        # type: docs (auto-detected)
3/archetypes/gallery.md     # type: gallery (auto-detected)
4/archetypes/projects.md    # type: projects (custom)
5/archetypes/tutorials.md   # type: tutorials (custom)
6/archetypes/docs-with-faq.md # type: docs with FAQ extension

Note

Not all types present in archetypes define layouts but they can be used to create content with specific types.

When you create a new content based on these archetype, use --kind flag to specify the type:

1hugo new  posts/my-first-post.md
2hugo new --kind docs <file-path>

Template Lookup Examples

Here’s how Hugo finds templates based on type:

 1# Content with type: docs
 2/content/installation.md (with type: docs)
 3→ Looks for: /layouts/docs/single.html
 4→ Falls back to: /layouts/_default/single.html
 5
 6# Content with type: gallery
 7/content/vacation-photos.md (with type: gallery)
 8→ Looks for: /layouts/gallery/single.html
 9→ Falls back to: /layouts/_default/single.html
10
11# Content in blog section (auto-detected)
12/content/blog/my-post.md (no type specified)
13→ Auto-detected as: type: blog
14→ Looks for: /layouts/blog/single.html
15→ Falls back to: /layouts/_default/single.html

Finding All Available Types

Use these commands to discover available types in your HBStack installation:

1# Find all type-specific layout directories
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -maxdepth 3 -path "*/layouts/*" -type d | grep -E "layouts/[^/]+$" | sed 's|.*/layouts/||' | grep -v "partials\|shortcodes\|_default" | sort | uniq
3
4# Results: archives, authors, blog, docs, gallery
5
6# Check your local archetypes
7find /home/ag-sayyed/Documents/projects-notes/archetypes/ -name "*.md" -exec basename {} .md \;
8
9# Results: blog, docs, docs-with-faq, gallery, projects, tutorials

Checking Type Usage in Templates

1# See how modules check for specific types
2grep -r "\.Type" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ --include="*.html"
3
4# Example findings:
5# {{- if eq .Page.Type "docs" }}        # docs module checking for docs type
6# .RegularPages.GroupBy "Type"          # blog module grouping by type

Creating Custom Types

You can create custom types by:

1. Creating an archetype: /archetypes/projects.md
2. Creating templates: /layouts/projects/single.html, /layouts/projects/list.html
3. Using in content: Set type: projects in frontmatter

Type-Specific Configuration

HBStack modules can have type-specific configuration:

1# From hbstack/docs module configuration
2[params.hb.full_width_types.docs]
3enable = true
4
5# This means docs type pages get full-width layout

Best Practices

1. Use existing types: Leverage blog, docs, gallery for rich functionality
2. Custom types for special content: Create custom types for unique content needs
3. Consistent organization: Keep similar content in the same type
4. Template inheritance: Custom types fall back to _default templates

Quick Type Reference

The type system is Hugo’s way of organizing content and determining which templates to use, while HBStack extends this with rich, specialized templates for different content types!

FAQs