Custom fonts in HTML output

Djockey’s default theme uses system-default fonts so pages load as quickly as possible. But branding and aesthetics matter too, so Djockey makes it relatively straightforward to use a custom font in HTML output.

You need two things in order to use a custom font: static files and custom CSS. Djockey makes it easy to add both.

By copying files into your docs

Download a WOFF2 file

If you download IBM Plex Sans from Fontsource, you could copy webfonts/ibm-plex-sans-latin-400-normal.woff2 into your_docs/ibm-plex-sans-latin-400-normal.woff2.

Write the CSS

For example, in your_docs/fonts.css:

@font-face {
  font-family: 'IBM Plex Sans';
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url(./ibm-plex-sans-latin-400-normal.woff2) format('woff2');
}

:root {
  font-family: 'IBM Plex Sans';
  --fw-bold: 700; /* Plex doesn't go up to 800, and Djockey's default bold is 800 */
  --f-body: "IBM Plex Sans", sans-serif;

  /* the other font CSS property you can override is --f-monospace. */
}

Boom, fancy font!

By using Fontsource from npm

Rather than copying files into your repo and writing custom CSS, you can install Fontsource fonts from NPM and use them. (This is what the Djockey docs already do.)

Install the library

npm install --dev @fontsource/ibm-plex-sans

Configure Djockey to include the necessary files

In djockey.yaml:

# ... rest of your config ...

html:
  extra_static_dirs:
    # Tell Djockey to look outside your docs directory for static files
    - path: ../node_modules/@fontsource/ibm-plex-sans
      prefix: "plex-sans" # make sure same-name CSS files don't overwrite each other
      patterns:
        # List all the files you need. Djockey's docs use four different
        # font weights, so there are a lot.
        # The paths/globs are relative to the path given above.
        - "300.css"
        - "300-italic.css"
        - "400.css"
        - "400-italic.css"
        - "600.css"
        - "600-italic.css"
        - "700.css"
        - "700-italic.css"
        - "files/ibm-plex-sans-latin-300-normal.woff2"
        - "files/ibm-plex-sans-latin-300-italic.woff2"
        - "files/ibm-plex-sans-latin-400-normal.woff2"
        - "files/ibm-plex-sans-latin-400-italic.woff2"
        - "files/ibm-plex-sans-latin-600-normal.woff2"
        - "files/ibm-plex-sans-latin-600-italic.woff2"
        - "files/ibm-plex-sans-latin-700-normal.woff2"
        - "files/ibm-plex-sans-latin-700-italic.woff2"

Override Djockey’s CSS properties so the font gets used

:root {
  font-family: 'IBM Plex Sans';
  --fw-bold: 700; /* Plex doesn't go up to 800, and Djockey's default bold is 800 */
  --f-body: "IBM Plex Sans", sans-serif;

  /* the other font CSS property you can override is --f-monospace. */
}

Some nice fonts to use

Here are some readable sans-serif fonts with support for lots of Unicode glyphs:

Source Sans from Adobe
Fira Sans from Mozilla
Plex Sans from IBM
Inter by Rasmus Andersson
Cooper Hewitt by Chester Jenkins for the Smithsonian
B612 by Airbus

For monospace fonts, I won’t make any recommendations, because chances are good that if you’re a programmer then you have your own strong opinion. Djockey’s default monospace font stack tries to use the best font on each system.