Customizing Doks

Custom fonts#

By default, Doks uses the Jost font created by indestructible type* for all text.

If you want to add a custom font to your Doks site, you can set up fonts to use in custom CSS files.

System fonts#

Using system fonts ensures documentation loads quickly in a font that is familiar to each user, without requiring extra bandwidth to download large font files.

If you’d like to use system fonts, add to assets/scss/common/_variables-custom.scss:

// $font-family-sans-serif:      "Jost", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
$font-family-sans-serif:
  system-ui,
  -apple-system,
  "Segoe UI",
  Roboto,
  "Helvetica Neue",
  "Noto Sans",
  "Liberation Sans",
  Arial,
  sans-serif,
  "Apple Color Emoji",
  "Segoe UI Emoji",
  "Segoe UI Symbol",
  "Noto Color Emoji";

Google Fonts#

If you’d like to use Google Fonts, the recommended way (for performance reasons) is to self-host the fonts with the help of a tool like for example google-webfonts-helper or Fontsource.

If you’d like to use the “Montserrat” font for example:

1. Visit google-webfonts-helper, select “Monserrat”, charset “latin”, styles “regular” and “500”.

2. Copy CSS for modern browsers (use folder prefix /fonts/montserrat/) and paste in assets/scss/common/custom.scss:

   // Put your custom SCSS code here
   
   /* montserrat-regular - latin */
   @font-face {
     font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */
     font-family: "Montserrat";
     font-style: normal;
     font-weight: 400;
     src: url("/fonts/montserrat/montserrat-v26-latin-regular.woff2") format("woff2"); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */
   }
   /* montserrat-500 - latin */
   @font-face {
     font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */
     font-family: "Montserrat";
     font-style: normal;
     font-weight: 500;
     src: url("/fonts/montserrat/montserrat-v26-latin-500.woff2") format("woff2"); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */
   }

3. Download files, extract, and paste fonts in /static/fonts/montserrat/.

4. Add to assets/scss/common/_variables-custom.scss:

   // $font-family-sans-serif:      "Jost", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   $font-family-sans-serif:
     "Montserrat",
     system-ui,
     -apple-system,
     "Segoe UI",
     Roboto,
     "Helvetica Neue",
     "Noto Sans",
     "Liberation Sans",
     Arial,
     sans-serif,
     "Apple Color Emoji",
     "Segoe UI Emoji",
     "Segoe UI Symbol",
     "Noto Color Emoji";

5. Avoid Cumulative Layout Shift by preloading the fonts: copy node_modules/@hyas/doks-core/layouts/partials/head/resource-hints.html to layouts/partials/head/resource-hints.html and add — for example:

   <link rel="preload" href="{{ "fonts/montserrat/montserrat-v26-latin-regular.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
   <link rel="preload" href="{{ "fonts/montserrat/montserrat-v26-latin-500.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>