# Working a Hugo website
## The Rendering Pipeline
- Global settings are defined in `hugo.toml`, like theme, params, baseURL, and build/minify behavior.
- `baseof.html`[^2] 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**
1. Hugo renders `layouts/index.html` , which starts with `{{ define "main" }}` to define a main block to replace the one in `baseof.html`.
2. Hugo renders the base template
3. `index.html` pulls in partials from `layouts/partials/…`.
4. Partials pull data from `data/homepage.yaml` (and `.Site.Params` in `hugo.toml`).
5. HTML files use compiled CSS from `assets/custom.scss`[^1].
---
## To add a section
To add (or remove) a section, modify the following files:
1. Add the content data for the new section in `data/homepage.yaml`
2. Create `layouts/partials/newSection.html`
3. 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 }}
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.
[^1]: via Hugo Pipes / Dart Sass
[^2]: In `/layouts/_default/baseof.html`