Working a Hugo website

The Rendering Pipeline

Global settings are defined in hugo.toml, like theme, params, baseURL, and build/minify behavior.
baseof.html¹ provides the core HTML structure shared by all pages, including:
- HTML boilerplate
- Site-wide metadata (charset, viewport)
- Title generation
- CSS and navigation bar
- A placeholder block {{ block "main" . }}{{ end }} for page-specific content
- Footer
index.html is the homepage template - It extends the base template and fills in the main block with homepage-specific content organized in partials.

Processing

Hugo renders layouts/index.html , which starts with {{ define "main" }} to define a main block to replace the one in baseof.html.
Hugo renders the base template
index.html pulls in partials from layouts/partials/….
Partials pull data from data/homepage.yaml (and .Site.Params in hugo.toml).
HTML files use compiled CSS from assets/custom.scss².

To add a section

To add (or remove) a section, modify the following files:

Add the content data for the new section in data/homepage.yaml
Create layouts/partials/newSection.html
Update layouts/index.html to call the new partial at the place you want it to show

File-by-file: roles and interplay

1) `assets/custom.scss` (your SCSS entry point)

What it is: An SCSS source file that Hugo compiles into CSS using Hugo Pipes with Dart Sass (you’re on Hugo Extended via v0.154.2, so that’s supported).
What it does:
- Imports Bulma v1 (either via @use/@forward if you vendored it under assets/, or a pre-bundled CSS file if you prefer).
- Sets Bulma variables (colors, spacing, breakpoints) before importing Bulma to override defaults.
- Adds your theme overrides for Fresh components/sections and custom utilities.
How it’s wired in:\ A head partial (commonly something like layouts/partials/head.html) will contain Hugo Pipes calls:

{{ $styles := resources.Get "custom.scss" | toCSS (dict "targetPath" "assets/custom.css") | minify | fingerprint }}

This line is what connects your SCSS to the HTML. If you don’t see it yet, add it to your head partial.

Override rules: If the theme also ships a assets/custom.scss, your project-level assets/custom.scss overrides the theme’s because of Hugo’s lookup order.

2) `layouts/index.html` (homepage template)

What it is: The template used for the site’s root (/). Hugo’s template lookup will use this file if present in your project (it overrides the theme’s index.html).
What it does:
- Defines the page structure of your homepage.
- Includes partials that render each section (hero, features, testimonials, CTAs).
- Passes data to partials—commonly from .Site.Data.homepage (i.e., data/homepage.yaml) or .Site.Params.
Typical pattern:

{{ define "main" }}

{{ partial "hero.html" (dict "ctx" . "data" .Site.Data.homepage.hero) }}

{{ partial "features.html" (dict "ctx" . "data" .Site.Data.homepage.features) }}

{{ partial "cta.html" (dict "ctx" . "data" .Site.Data.homepage.cta) }}

{{ end }}

This shows how the template connects to your data file.

3) `layouts/partials/` (reusable sections & head)

What it is: A folder of small templates used by pages (and other partials).
What it does:
- Renders modular sections like hero.html, navbar.html, footer.html, features.html, pricing.html, etc.
- Contains head.html or similar where you wire in assets/custom.scss via Hugo Pipes (see above).
- Optionally injects JavaScript assets (minified/fingerprinted in a similar way).
How it connects:\ Partials receive a context. If you pass a dict with "data", the partial can render purely from that structure:

{{ $d := .data }}


{{ $d.title }}


{{ $d.subtitle }}

    {{ with $d.buttons }}



        {{ range . }}

          {{ .label }}

        {{ end }}



    {{ end }}

This keeps your content in data/homepage.yaml and your structure in partials.

Override rules: Project partials in layouts/partials/ override theme partials of the same path/name. This is how you customize Fresh without forking the theme.

4) `data/homepage.yaml` (structured content for the homepage)

What it is: A data file (YAML) containing content & per-section settings for the homepage: texts, images, lists, buttons, visibility flags.
What it does:
- Decouples content from templates: editors can update text without touching HTML/SCSS.
- Supplies data to partials via .Site.Data.homepage or by passing nested keys.
Typical shape (example):

hero:

title: "Build fast with Fresh + Bulma v1"

subtitle: "A clean landing page powered by Hugo"

buttons:

    - label: "Get Started"

      url: "/docs"

      color: "primary"

    - label: "GitHub"

      url: "https://github.com/…"

      color: "light"

features:

items:

    - icon: "rocket"

      title: "Speedy"

      text: "Hugo builds are blazing fast."

    - icon: "feather"

      title: "Lightweight"

      text: "No heavy JS framework required."
How it connects:\ A partial will read it like .Site.Data.homepage.hero.title (or via the "data" key passed from the index template).

Override rules: Your project’s data/ completely defines the data used. If the theme ships default YAML in its data/, your project’s files win.

Common customization patterns

Change copy or lists → edit data/homepage.yaml.
Change section structure or classes → edit the corresponding layouts/partials/*.html.
Add a new section →
1. create a new partial layouts/partials/your-section.html,
2. add data under data/homepage.yaml (e.g., yourSection:),
3. include the partial from layouts/index.html: {{ partial "your-section.html" (dict "ctx" . "data" .Site.Data.homepage.yourSection) }}
Adjust colors/spacing/fonts → edit assets/custom.scss (set Bulma variables before importing Bulma; add your custom rules after).
Add/optimize assets → wire them in the head/footer partials with Hugo Pipes (minify, fingerprint).

Notes for Bulma v1 + Dart Sass + Fresh

Variable overrides:\ With Dart Sass, prefer @use/@forward:

// assets/custom.scss

@use "bulma/sass" with (

$primary: #4e7cf3,

$family-sans-serif: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif,

$body-background-color: #fff

);

// Your component overrides after Bulma is loaded

.navbar.is-transparent { background-color: transparent; }

Ensure Bulma’s source is available under assets/ (e.g., assets/bulma/…) or adjust the import path accordingly.
Lookup order helps you customize safely:\ Put overrides in your project (layouts, assets, data). You avoid forking the theme and keep upgrades simpler.

Quick sanity checklist

Head partial includes your SCSS: Confirm a link tag is generated via resources.Get "custom.scss" | toCSS ….
Homepage uses your index.html: Run hugo server and check logs for which template is used; or temporarily change a heading to confirm it’s picked.
Partials receive data: Log output with {{ printf "%#v" .data }} inside a partial (temporarily) to confirm data structure.
Data keys match partial expectations: If a partial expects .data.items, ensure data/homepage.yaml has items: under the right section.
Minify/fingerprint on production: Useful for caching; keep minify = true and use fingerprint.

If you share a snippet of your current layouts/index.html, one sample partial, and the top of assets/custom.scss, I can review the wiring and suggest the cleanest way to structure imports for Bulma v1 and your Fresh overrides.

In /layouts/_default/baseof.html ↩︎
via Hugo Pipes / Dart Sass ↩︎

8.7 KiB Raw Permalink Blame History Unescape Escape

Working a Hugo website

The Rendering Pipeline

To add a section

File-by-file: roles and interplay

1) assets/custom.scss (your SCSS entry point)

2) layouts/index.html (homepage template)

3) layouts/partials/ (reusable sections & head)

{{ $d.title }}

4) data/homepage.yaml (structured content for the homepage)