Typography

Configure fonts for your HugoBlox site — use built-in font packs, bundle your own fonts locally, or load any Google Font.

HugoBlox's typography system gives you full control over fonts with zero CSS. Choose a curated font pack, customize individual families, or bring your own fonts — locally bundled or from Google Fonts.

Build your theme visually

Use the HugoBlox Theme Builder to preview font packs and build a custom theme online — then copy the config to your site.

Quick Start

Set a font pack in config/_default/params.yaml:

hugoblox:
  typography:
    pack: "modern"

That's it. The pack defines heading, body, and code fonts with coordinated weights, sizes, and spacing.

Font Packs

Each pack is a curated set of fonts designed to work together. HugoBlox ships with 7 built-in packs:

Pack	Heading	Body	Code	Vibe
`modern`	Inter	Inter	JetBrains Mono	Clean, default look
`geometric`	Montserrat	Poppins	JetBrains Mono	Bold, structured
`humanist`	Nunito	Open Sans	Ubuntu Mono	Friendly, approachable
`developer`	Space Grotesk	IBM Plex Sans	Fira Code	Technical, precise

Pack	Heading	Body	Code	Vibe
`academic`	Lora	Source Serif 4	Source Code Pro	Scholarly, traditional
`editorial`	Playfair Display	Merriweather	Source Code Pro	Elegant, editorial

Pack	Heading	Body	Code	Vibe
`system`	OS sans-serif	OS sans-serif	OS monospace	Fastest (no download)

The modern pack (Inter + JetBrains Mono) loads entirely from local bundled files — zero network requests for fonts, giving you the best of both worlds: great typography and maximum performance.

How Fonts Are Loaded

HugoBlox resolves each font family through three tiers, in priority order:

Priority	Source	When Used	Performance
1	System fonts	Font name is `system-sans`, `system-serif`, or `system-mono`	Instant (no download)
2	Bundled files	A matching `.woff2` or `.ttf` exists in `assets/dist/font/`	Fast (local file)
3	Google Fonts CDN	No local bundle found	Good (cached CDN)

This means:

The system pack uses OS fonts — zero network requests
The modern pack auto-detects its bundled Inter and JetBrains Mono files — zero network requests
Other packs (e.g. academic, geometric) load from Google Fonts CDN with display=swap for smooth rendering
Mixed mode works too: if some fonts in a pack are bundled and others aren't, each resolves independently

Bundling Your Own Fonts

Want to self-host a Google Font for privacy, performance, or offline use? Drop the font file into your site and HugoBlox will use it automatically.

Download the font

Get .woff2 (preferred) or .ttf files from Google Fonts or your font vendor.

For variable fonts, download the variable weight version — it covers all weights in a single file.
Name the file correctly

Follow this naming convention (spaces removed from family name):

Font Type File Name Example
Variable <Name>.var.woff2 Lora.var.woff2
Variable (TTF) <Name>.var.ttf Lora.var.ttf
Static weight <Name>-<weight>.woff2 Lora-700.woff2
Place it in your site's font directory

Lora.var.woff2
params.yaml

Create the assets/dist/font/ directory if it doesn't exist.

Font Type	File Name	Example
Variable	`<Name>.var.woff2`	`Lora.var.woff2`
Variable (TTF)	`<Name>.var.ttf`	`Lora.var.ttf`
Static weight	`<Name>-<weight>.woff2`	`Lora-700.woff2`

Use the font in your config (if not already)

hugoblox:
  typography:
    pack: "academic"  # Lora is the heading font in this pack

Or override a specific family:

hugoblox:
  typography:
    pack: "modern"
    families:
      heading: "Lora"  # Now uses your bundled file

HugoBlox auto-detects the bundled file and emits a local @font-face declaration instead of fetching from Google Fonts. No other config needed.

File naming matters

The file name must start with the font family name (spaces removed). Lora.var.woff2 matches the font family "Lora". lora-variable.woff2 will not match.

What HugoBlox ships with

The framework bundles two fonts out of the box, used by the default modern pack:

Font	File	Format	Size
Inter	`Inter.var.woff2`	WOFF2 (variable)	317 KB
JetBrains Mono	`JetBrainsMono.var.ttf`	TTF (variable)	189 KB

These are available to all sites using HugoBlox — no manual download needed.

Customizing Font Families

Override individual families while keeping the rest of the pack:

hugoblox:
  typography:
    pack: "modern"
    families:
      heading: "Playfair Display"  # Override just heading
      body: "Inter"                # Keep body from pack
      code: "Fira Code"           # Override code font

You can set any of these roles:

Role	Used For
`heading`	`h1`–`h6` elements
`body`	Paragraph text, lists, general content
`code`	`<code>`, `<pre>`, and code blocks
`nav`	Navigation menu (defaults to heading font)

Any font name that isn't system-sans, system-serif, or system-mono — and doesn't have a matching bundled file — will be loaded from Google Fonts automatically.

Font Weights

Configure which weights are loaded per role:

hugoblox:
  typography:
    pack: "modern"
    weights:
      heading: [600, 700]
      body: [400, 500]
      code: [400]
    variable:
      heading: true   # Load as variable font (full weight range)
      body: true
      code: true

When variable: true, Google Fonts loads the full 100..900 weight range in one request
When variable: false, only the specific weights listed are loaded
For bundled variable font files (those with .var. in the filename), the full weight range is always available regardless of this setting

Text Size Scale

hugoblox:
  typography:
    sizes:
      base: "1rem"      # 16px default
      sm: "0.875rem"    # 14px
      lg: "1.125rem"    # 18px

Preset	Base Size	Best For
`1rem` (16px)	Recommended for most sites	General use
`0.875rem` (14px)	Dense content	Dashboards, data-heavy pages
`1.125rem` (18px)	Readability focus	Blogs, long-form content
`1.25rem` (20px)	Accessibility	Large screens, visually impaired readers

Line Height & Letter Spacing

Fine-tune readability:

hugoblox:
  typography:
    leading:
      heading: 1.2     # Tight for headings
      body: 1.6        # Comfortable for reading
      code: 1.5        # Balanced for code
    tracking:
      heading: "-0.02em"  # Slightly tighter headings
      body: "0"
      caps: "0.05em"      # Spacious for uppercase text

Creating a Custom Font Pack

For full control, create your own font pack as a YAML file:

Create the pack file
```
data/fonts/my-brand.yaml
```

Define the pack

hugoblox:
  meta:
    format: "hugoblox-font@1"
    name: "My Brand"
    vendor: "hugoblox"
    version: "1.0.0"
    license: "MIT"
    style: "sans"  # "sans" or "serif" — sets the generic fallback
    description: "Custom brand typography"

  families:
    heading: "Outfit"
    body: "Inter"
    code: "JetBrains Mono"

  weights:
    heading: [600, 700]
    body: [400, 500]
    code: [400]

  leading:
    heading: 1.2
    body: 1.6
    code: 1.5

  tracking:
    heading: "-0.02em"
    body: "0"

  variable:
    heading: true
    body: true
    code: true

Use it in your config

hugoblox:
  typography:
    pack: "my-brand"

Pair a custom font pack with bundled font files for a fully self-hosted typography setup with zero external requests.

Performance Comparison

Setup	Font Requests	Render Blocking	Privacy
`system` pack	0	None	Full (no 3rd-party)
`modern` pack (bundled)	0	None	Full (no 3rd-party)
Other packs (Google CDN)	1–3	Minimized (`display=swap`)	Google Fonts request
Custom bundled fonts	0	None	Full (no 3rd-party)

Privacy & GDPR

If you need to avoid third-party requests for GDPR compliance, use the system pack, the modern pack, or bundle your own fonts. All three options make zero external font requests.

🙋 FAQ

Quick Start

Font Packs

How Fonts Are Loaded

Bundling Your Own Fonts

What HugoBlox ships with

Customizing Font Families

Font Weights

Text Size Scale

Line Height & Letter Spacing

Creating a Custom Font Pack

Performance Comparison

🙋 FAQ

Theming & Appearance

Performance Guide

Theme Builder

Extend & Hooks

Was this page helpful?

On this page