Extend & Customize HugoBlox

HugoBlox is designed to be extensible. Whether you need a simple CSS tweak or a complex third-party integration, you can do it without modifying the core theme files.

Hooks

Inject custom code (like analytics, popups, or meta tags) into specific parts of your site using Hooks.

Locations

Hook	Description	Common Use Cases
head-end	Just before </head>	Meta tags, tracking scripts
body-end	Just before </body>	Chat widgets, analytics
footer-start	Inside footer	Custom copyright, links

How to Use

1. Create the hook file path.
2. Add your HTML/JS code.

• Directorylayouts/

  • Directorypartials/

    • Directoryhooks/

      • Directoryhead-end/

        • custom-meta.html
      • Directorybody-end/

        • analytics.html

Example: Add a Script

To add a custom script to the end of the body:

1. Create layouts/partials/hooks/body-end/myscript.html.

2. Add your code:

   <script>
     console.log("Hello from custom hook!");
   </script>

Custom Styling (CSS)

Override or add new styles.

1. Create assets/css/custom.css.

2. Add your CSS.

   assets/css/custom.css

   .my-custom-class {
     color: red;
   }

Overriding Components

Hugo’s Lookup Order allows you to replace any official layout file by creating a copy in your local layouts/ folder.

1. Identify the File Find the file you want to change in the HugoBlox repository.

   • Example: layouts/_partials/components/headers/navbar.html

2. Copy to Local Create the same folder structure in your site root and paste the file.

   • Example: layouts/_partials/components/headers/navbar.html

3. Modify Edit your local copy. Hugo will use it instead of HugoBlox’s version.

Caution

Only override files if absolutely necessary. You will need to manually update your overrides when HugoBlox updates.

Try to use the Hooks, Styles, or Plugin system instead. With the Plugin system, you can create new blocks and listing views.

Advanced Customization

Creating New Blocks

Use the Blox System to create reusable content blocks.

content/_index.md

sections:
  - block: my-custom-block
    content:
      title: My Block

Create your Go HTML template at layouts/_partials/hbx/blocks/my-custom-block/block.html.

Check out the existing blocks for inspiration.

Theme-Aware JavaScript

Listen for theme changes (Light/Dark mode) in your custom scripts.

document.addEventListener('hbThemeChange', (e) => {
    const isDark = e.detail.isDarkTheme();
    console.log('Theme changed to:', isDark ? 'Dark' : 'Light');
});