# 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 }}
    
    <link rel="stylesheet" href="{{ $styles.RelPermalink }}" integrity="{{ $styles.Data.Integrity }}">
    
    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 }}
    
    <section class="section hero is-primary">
    
      <div class="container">
    
        <h1 class="title">{{ $d.title }}</h1>
    
        <p class="subtitle">{{ $d.subtitle }}</p>
    
        {{ with $d.buttons }}
    
          <div class="buttons">
    
            {{ range . }}
    
              <a class="button is-{{ .color }}" href="{{ .url }}">{{ .label }}</a>
    
            {{ end }}
    
          </div>
    
        {{ end }}
    
      </div>
    
    </section>
    
    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`
