如何在 mdbook 中配置在生成的书中自动使用的自定义字体？

Question

几天前我发现了mdBook。寻找一个简单、小型、不超载的静态站点生成器，我很兴奋。它易于使用、简单、快速且设计完善。

尽管设置简单快速，但细节却存在问题。我想调整自定义主题中的字体。

在 mdBook 手册中，仅在HTML 渲染器选项中提到了字体配置的可能性：“copy-fonts”配置选项将“fonts.css”和相应的字体文件复制到输出目录，以在默认主题中使用。但是阅读上面的一些要点，“默认主题”被定义为在“更改主题”下拉列表中默认选择的主题配色方案。

这是如何结合在一起的？在我的配置中，字体文件的自动复制不起作用。我编写了一个小 bash 脚本，用于在构建书籍输出后进行复制。

所以我想描述一下我所做的配置步骤：

1. 通过将默认主题的基本文件复制到单独的目录中来设置一本新书：

   mdbook init testBook --theme
   

2. 将“主题”目录重命名为“peters-theme”

3. 创建新目录“peters-theme/fonts”

• 将 Libertinus TeX 字体复制到此目录中

• 创建一个新的CSS文件'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. 调整文件“peters-theme/css/general.css”

• 添加额外的 css 导入规则

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

• 更改 HTML 选择器

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

5. 创建文件“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. 将字体文件放入“peters-theme/fonts”目录中

• '彼得斯主题/字体/LibertinusSans-Bold.otf'
• '彼得斯主题/字体/LibertinusSans-Italic.otf'
• '彼得斯主题/字体/LibertinusSans-Regular.otf'

7. 调整文件“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. 创建 bash 脚本“build-book.sh”（使用复制作为解决方法）

   #!/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
   

问候

彼得

Answer 1

附加信息

不幸的是，上面的第一个提示并没有完全解决问题。它会导致一种效果：自定义字体 css 文件会自动复制到正确的子目录中。它的新位置是

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

因此，我相应地更改了文件“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 }}peters-theme/fonts/libertinus-sans-font.css">
{{/if}}

但问题的一部分仍然存在。本地字体文件不会复制到目标“book/fonts”目录。

环顾四周已完成的拉取请求，我找到了 这个。根据描述，我更改了“book.toml”配置文件并添加了一个新的“output.html.font”部分。

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

此处列出了完整的“book.toml”配置文件：

[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

另外，我更改了字体 css 文件“peters-theme/fonts/libertinus-sans-font.css”以匹配 woff 字体类型。

@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');
}

woff 字体文件位于“peters-theme/fonts”目录中

• '彼得斯主题/字体/LibertinusSans-Bold.woff'
• 'peters-theme/fonts/LibertinusSans-Italic.woff'
• 'peters-theme/fonts/LibertinusSans-Regular.woff'

我希望这些本地字体文件被复制到输出目录......但这并没有发生。

现在我希望得到一个黄金提示我做错了什么。

向你问好

彼得