237 lines
8.7 KiB
Markdown
237 lines
8.7 KiB
Markdown
# 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`
|