Skip to content

Fonts

Jump to bottom
Regis Philibert edited this page Dec 2, 2022 · 9 revisions

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
preload:
  - woff2
  - ttf
base:
  display: swap
fonts:
- family: Open
  file: fonts/open-sans-v17-latin-300
  weight: 300
  style: normal
- family: Open
  file: fonts/open-sans-v17-latin-700
  weight: 700
- family: ComicSans
  weight: 400
  file: fonts/comic-sans-oh-no
  preload:
  - eot

Hugo template

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

HTML

<head>
<!-- fonts -->
<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-300.ttf" rel="preload">
<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-300.woff2" rel="preload">
<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-700.ttf" rel="preload">
<link as="font" crossorigin="anonymous" href="/fonts/open-sans-v17-latin-700.woff2" rel="preload">
<style >
@font-face {
  font-display: swap;
  font-family: Open;
  font-style: normal;
  font-weight: 400;
  src: local("Open"),
url("/fonts/open-sans-v17-latin-400.ttf") format("ttf"),
url("/fonts/open-sans-v17-latin-400.woff2") format("woff2");
}
@font-face {
  font-display: swap;
  font-family: Open;
  font-weight: 700;
  src: local("Open"),
url("/fonts/open-sans-v17-latin-300italic.ttf") format("ttf"),
url("/fonts/open-sans-v17-latin-300italic.woff2") format("woff2");
}
@font-face {
  font-family: ComicSans;
  font-weight: 400;
  src: local("ComicSans"),
url("/fonts/comic-sans-oh-no.eot") format("embedded-opentype");
}
</style>
</head>

How it works?

HUGE will look for each font declaration and create a @fontface declaration with the passed selectors with all the src property functions (url, format, 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

A boolean or a slice of formats. This defines which files shall be preloaded for every font.

Preload

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 of some of the declared scripts in the templates. There is no required parameters.

Example

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

This is a HUGE WIP right now! Stay tune for more info as we push it to Alpha!

Clone this wiki locally