How to configure custom fonts in mdbook that are used automatically in the generated book?

Question

Few days ago I found mdBook. Looking around for an easy, small, not oveloaded static site generator, I'm excited. It's easy to use, simple, fast and completely well designed.

In spite of an easy an fast setup, details hold problems inside. I'd like to tweak the font in a customized theme.

In the mdBook manual font configuration possibilities are only mentioned with the HTML renderer options: A 'copy-fonts' config option copies 'fonts.css' and respective font files to the output directory to be used in the default theme. But reading a few bullet points above 'default-theme' is defined as the theme color scheme to select by default in the 'Change Theme' dropdown.

How does that fit together? In my configuration the automatic copying of font files does not work. I wrote a little bash script that does the copying after building book output.

So I'd like to describe the configuration steps I did:

1. set up a new book with copying the default theme's basic files into a separate directory:

   mdbook init testBook --theme
   

2. rename the 'theme' directory to 'peters-theme'

3. create new directory 'peters-theme/fonts

• copy the Libertinus TeX font into this directory

• create a new css file 'peters-theme/fonts/libertinus-sans-font.css'

  @font-face {
  font-family: libertinus-sans;
  font-style: normal;
  font-weight: normal;
  src: url('LibertinusSans-Regular.otf') format('opentype');
  }
  
  @font-face {
  font-family: libertinus-sans;
  font-style: italic;
  font-weight: normal;
  src: url('LibertinusSans-Italic.otf') format('opentype');
  }
  
  @font-face {
  font-family: libertinus-sans;
  font-style: normal;
  font-weight: bold;
  src: url('LibertinusSans-Bold.otf') format('opentype');
  }
  

4. tweak file 'peters-theme/css/general.css'

• add additional css import rule

  @import '../fonts/libertinus-sans-font.css'; /* added individually: use 'libertinus sans' fonts */
  

• change HTML selector

  html {
      font-family: libertinus-sans; /* added individually: use 'libertinus sans' fonts */
      color: var(--fg);
      background-color: var(--bg);
      text-size-adjust: none;
  }
  

5. create file 'peters-theme/fonts/libertinus-sans-font.css'

   @font-face {
   font-family: libertinus-sans;
   font-style: normal;
   font-weight: normal;
   src: url('LibertinusSans-Regular.otf') format('opentype');
   }
   
   @font-face {
   font-family: libertinus-sans;
   font-style: italic;
   font-weight: normal;
   src: url('LibertinusSans-Italic.otf') format('opentype');
   }
   
   @font-face {
   font-family: libertinus-sans;
   font-style: normal;
   font-weight: bold;
   src: url('LibertinusSans-Bold.otf') format('opentype');
   }
   

6. place font files into 'peters-theme/fonts' directory

• 'peters-theme/fonts/LibertinusSans-Bold.otf'
• 'peters-theme/fonts/LibertinusSans-Italic.otf'
• 'peters-theme/fonts/LibertinusSans-Regular.otf'

7. tweak file 'peters-theme/index.hbs'

   <!-- Fonts -->
   <link rel="stylesheet" href="{{ path_to_root }}FontAwesome/css/font-awesome.css">
   {{#if copy_fonts}}
   <!-- added additionally to include custom font CSS -->
   <link rel="stylesheet" href="{{ path_to_root }}fonts/libertinus-sans-font.css">
   {{/if}}
   

8. create bash script 'build-book.sh' (with copying as workaround)

   #!/bin/bash
   #
   # Author: Peter
   # Date: 2020-11-20
   #
   ROOTFOLDER='/home/peter/Documents/Peter/Notes/mdBook/testBook/'
   #
   # change to book directory
   cd $ROOTFOLDER
   #
   # clean up old book files
   mdbook clean
   #
   # build the book
   mdbook build
   #
   # copy fonts for custom theme
   cp -r ./peters-theme/fonts/ ./book/
   #
   # display book in browser
   mdbook serve --open
   

Greetings

Peter

Answer 1

Additional information

Unfortunately, the first hint above doesn't solve the problem completely. It causes one effects: The custom font css file is copied to the correct subdirectory automatically. It's new location is

book/peters-theme/fonts/libertinus-sans-font.css

In consequence, I changed the tweak of file 'peters-theme/index.hbs' accordingly.

<!-- Fonts -->
<link rel="stylesheet" 
href="{{ path_to_root }}FontAwesome/css/font-awesome.css">
{{#if copy_fonts}}
<!-- added additionally to include custom font CSS -->
<link rel="stylesheet" 
href="{{ path_to_root }}peters-theme/fonts/libertinus-sans-font.css">
{{/if}}

But one part of the problem is remaining. The local font files are not copied to the destination 'book/fonts' directory.

Looking around at fulfilled pull requests led me to this one. Following the descriptions, I changed the 'book.toml' configuration file and added one new 'output.html.font' section.

[output.html.font]
enable = true
woff = true

The complete 'book.toml' configuration file is listed here:

[book]
title = "Rust Never Sleeps"
description = "An adventure getting in touch with mdBook and Rust"
author = "Peter"
language = "en"
multilingual = false
src = "src"

[output.html]
theme = "peters-theme"
default-theme = "rust"
copy-fonts = true
additional-css = ["peters-theme/fonts/libertinus-sans-font.css"]

[output.html.font]
enable = true
woff = true

Additionally I changed the font css file 'peters-theme/fonts/libertinus-sans-font.css' to match the woff font type.

@font-face {
font-family: libertinus-sans;
font-style: normal;
font-weight: normal;
src: url('LibertinusSans-Regular.woff') format('woff');
}

@font-face {
font-family: libertinus-sans;
font-style: italic;
font-weight: normal;
src: url('LibertinusSans-Italic.woff') format('woff');
}

@font-face {
font-family: libertinus-sans;
font-style: normal;
font-weight: bold;
src: url('LibertinusSans-Bold.woff') format('woff');
}

The woff font files are located in a 'peters-theme/fonts' directory

• 'peters-theme/fonts/LibertinusSans-Bold.woff'
• 'peters-theme/fonts/LibertinusSans-Italic.woff'
• 'peters-theme/fonts/LibertinusSans-Regular.woff'

I would expect that these local font files are copied to the output directory... But this isn't happening.

Now I hope getting a golden hint what I'm doing wrong.

Greetings to you

Peter