Skip to content
HugoBlox Docs

HBX Resolver Engine

The HBX Resolver is the engine powering HugoBlox’s modular architecture. It dynamically resolves block definitions (Blox) from your content front matter into rendered HTML components.

Core Concepts

Section titled “Core Concepts”

Dynamic Loading

Blocks are loaded on-demand based on your content configuration.

Schema Validation

Parameters are validated against JSON schemas for type safety.

Extensible

Create custom blocks without modifying the core engine.

Block Structure

Section titled “Block Structure”

A Block (Blox) is a self-contained component consisting of a template and an optional schema.

  • Directorylayouts/
    • Directorypartials/
      • Directoryblox/
        • Directorymy-block/
          • block.html # The Handlebars template
          • schema.json # (Optional) parameter validation

Usage

Section titled “Usage”

Blocks are typically used in landing pages within the sections list.

content/_index.md
type: landing
sections:
  - block: markdown
    content:
      title: Hello World
      text: This is a markdown block
  - block: collection
    content:
      title: Recent Posts
      filters:
        folders:
          - post

How it Works

Section titled “How it Works”
  1. Definition: You define a list of sections in your page front matter.
  2. Resolution: Hugo iterates through each section and looks for the block parameter.
  3. Lookup: The HBX Resolver searches for a matching template in layouts/partials/blox/<block-name>/block.html.
  4. Rendering: If found, the template is rendered with the section parameters as context.

Developing Custom Blocks

Section titled “Developing Custom Blocks”

Create your own blocks to extend HugoBlox functionality.

1. Create the Template

Section titled “1. Create the Template”

Create layouts/partials/blox/my-custom-block/block.html.

{{/* layouts/partials/blox/my-custom-block/block.html */}}
{{ $block := . }}
{{ $title := $block.content.title | default "Default Title" }}


<section class="my-custom-block p-8">
  <h2 class="text-2xl font-bold">{{ $title }}</h2>
  <div class="content">
    {{ $block.content.text | markdownify }}
  </div>
</section>

2. Use it in Content

Section titled “2. Use it in Content”
sections:
  - block: my-custom-block
    content:
      title: My New Block
      text: It works!

Schema Validation (Advanced)

Section titled “Schema Validation (Advanced)”

You can define a schema.json to enforce parameter types and defaults.

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "content": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "text": { "type": "string" }
      },
      "required": ["title"]
    }
  }
}