Fonts

HUGE/Fonts handles the project's self hosted fonts by producing the appropriate fontface declarations and prefetching.

TL;DR:

HUGE Config

# _huge/config/fonts.yaml
cascade:
  preload:
    - woff2
  display: swap
fonts:
- family: Open
  file: fonts/open-sans-v17-latin-regular
  weight: 300
  style: normal
- family: Open
  file: fonts/open-sans-v17-latin-italic
  weight: 400
  style: italic
- family: Roboto Flex
  file: fonts/RobotoFlex-VariableFont
  tech: variations
  weight: 100 700
  preload:
    - truetype

Hugo template

<head>
<!-- fonts -->
{{ partial "huge/fonts/tags "any" }}
</head>

HTML

<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-regular.woff2" rel="preload" type="font/woff2">
<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-italic.woff2" rel="preload" type="font/woff2">
<link as="font" crossorigin="anonymous" href="/fonts/RobotoFlex-VariableFont.ttf" rel="preload" type="font/ttf">
<style >
@font-face {
  font-display: swap;
  font-family: "Open";
  font-style: normal;
  font-weight: 300;
  src: local("Open"),
  url("/fonts/open-sans-v17-latin-regular.woff2") format("woff2"),
  url("/fonts/open-sans-v17-latin-regular.woff") format("woff"),
  url("/fonts/open-sans-v17-latin-regular.ttf") format("truetype");
}
@font-face {
  font-display: swap;
  font-family: "Open";
  font-style: italic;
  font-weight: 400;
  src: local("Open"),
  url("/fonts/open-sans-v17-latin-italic.woff2") format("woff2"),
  url("/fonts/open-sans-v17-latin-italic.woff") format("woff"),
  url("/fonts/open-sans-v17-latin-italic.ttf") format("truetype");
}
@font-face {
  font-display: swap;
  font-family: "Roboto Flex";
  font-weight: 100 700;
  src: url("/fonts/RobotoFlex-VariableFont.ttf") format("truetype") tech("variations");
}
</style>

How it works?

HUGE will look for each font declaration and create a @font-face at-rule with the passed selectors with all the src property functions (url, format, tech and the dreaded local of which you can opt out) for every files matching the passed basename.

Declaring the project's fonts

Users need to declare their fonts in the fonts key of _huge/config/fonts.{yaml|json|toml}

Each fonts declaration takes a number of parameters, only two being mandatory: the file and the family. Here is the list of available keys:

file*: The base filename (no extension!) relative to the assets directory for that given font.
family*: The name of the font family to which this file belongs two. Can be herited from base setting described below.
local: A boolean, a string or a slice. The string or list of strings which should be used for the local src (ex. src: local('My-Font'), url(...)). Can be set to false to opt out of local function src mention altogether. If set to true a local will be generated based on the font family name.
tech: A string. Defines the technology of the font. For variable fonts use "variations".
preload: A boolean or a slice of formats. This allow to overwrite the global preload setting detailed below for the given declaration. If a slice, only the font files whose format is in the slice will be preloaded.
{descriptor}: Any key and its value will be passed as a descriptor (font- prefix can be ommited).

Settings

Those are the global fonts settings.

`fonts`

The fonts declarations discussed above.

`cascade`

The cascade configuration key allows to have font settings cascade down to every font at-rule. It is useful to apply a global font-display strategy or simply pre-fill the most commonly used font-family.

# _huge/config/fonts.yaml
cascade:
  display: swap
  family: "Open"
  local: false
fonts:
- file: fonts/open-sans-v17-latin
  weight: 400
- file: fonts/open-sans-v17-latin-300italic
  style: italic
- family: Comic Sans
  file: fonts/oh-no-not-comic-sans
  local: Comic Sans

Preload strategy

The preload setting is set at the font level and takes a boolean or a slice of formats. With a boolean we'll simply preload all (true) or none (false) of the files found for that font. With a slice we'll only preload the files whose format is included in the slice.

Of course, using cascade, you can set a default preload strategy for every fonts.

# _huge/config/fonts.yaml
preload:
- woff2
fonts:
- family: Open
  file: fonts/open-sans-v17-latin
  weight: 400
- family: Comic Sans
  file: fonts/oh-no-not-comic-sans
  preload: false

WARNING: Formats are not extensions, we're expecting the exact keyword for the font formats listed on the @font-face at rule src documentation or the table below:

Keyword	Font Format	Common extensions
woff2	WOFF 2.0	.woff2
woff	WOFF 1.0	.woff
opentype	OpenType	.otf, .ttf
truetype	TrueType	.ttf
collection	OpenType Collection	.otc, .ttc
embedded-opentype	Embedded OpenType	.eot
svg	SVG Font (deprecated)	.svg, .svgz

Functions

`huge/fonts/tags`

The "huge/scripts/tags" partial is used to print the tags for this feature, namely the preload <link> tags and the <style> tag for the @font-face at-rules. There is no required parameters.

Example

{{ partial "huge/fonts/tags" "fonts" }}