Font preloading. Guide to custom fonts.

docs/src/changelog.dj

@@ -11,6 +11,7 @@ order: -1
 - Static file improvements
 
   - Static files can be added from outside the doc source directory
+  - WOFF2 files are preloaded
 
 - Many changes to the default theme
 

docs/src/features/asides.dj

@@ -7,7 +7,7 @@ order: -6
 ## Note
 
 {.dj-djot-demo}
-```
+```djot
 {tag=aside .note}
 :::
 Objects in mirror may be closer than they appear
@@ -17,7 +17,7 @@ Objects in mirror may be closer than they appear
 ## Tip
 
 {.dj-djot-demo}
-```
+```djot
 {tag=aside .tip}
 :::
 Objects in mirror may be closer than they appear
@@ -27,7 +27,7 @@ Objects in mirror may be closer than they appear
 ## Important
 
 {.dj-djot-demo}
-```
+```djot
 {tag=aside .important}
 :::
 Objects in mirror may be closer than they appear
@@ -37,7 +37,7 @@ Objects in mirror may be closer than they appear
 ## Caution
 
 {.dj-djot-demo}
-```
+```djot
 {tag=aside .caution}
 :::
 Objects in mirror may be closer than they appear
@@ -47,7 +47,7 @@ Objects in mirror may be closer than they appear
 ## Warning
 
 {.dj-djot-demo}
-```
+```djot
 {tag=aside .warning}
 :::
 Objects in mirror may be closer than they appear

docs/src/foundations/static_files.dj

@@ -2,10 +2,26 @@
 
 One design goal of Djockey is to minimize the need to edit a config file. In this spirit, all files that are not markup (i.e. not Markdown or Djot) are copied to the output directory.
 
-Any CSS and JavaScript files will be included in the HTML output. If your CSS file ends in `.light.css`{.lang-sh} or `.dark.css`{.lang-sh}, it will only be enabled for light or dark mode, respectively.
-
 If you name any files the same as any files in Djockey's template, your files will overwrite Djockey's files. Djockey uses a `dj-` prefix for all its static files, so you're unlikely to have a problem with this.
 
+## Automatic handling of CSS, JavaScript, and WOFF2
+
+### CSS
+
+All static files ending in `.css`{.language-sh} are included as `<link rel="stylesheet">`{.language-html} tags.
+
+If your CSS file ends in `.light.css`{.lang-sh} or `.dark.css`{.lang-sh}, it will only be enabled for light or dark mode, respectively.
+
+If you would like to prevent Djockey from doing this, you can add glob patterns to the `html.ignore_css` key in `djockey.yaml`{.language-sh}. For example, you would do this if you're [embedding TypeDoc's HTML output](#typedoc-integration) inside your Djockey docs.
+
+### JavaScript
+
+Any CSS and JavaScript files will be included in the HTML output. 
+
+### WOFF2
+
+All files ending in `.woff2`{.language-sh} will be preloaded in the HTML, to prevent any flashes of unstyled text before custom CSS loads.
+
 ## Links to static files
 
 If you link to a static file, the link will be verified at build time and a warning will be printed if no file can be found at the given path.

docs/src/guides/custom_fonts.dj

@@ -0,0 +1,75 @@
+# Custom fonts
+
+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](https://fontsource.org/fonts/ibm-plex-sans), you could copy `webfonts/ibm-plex-sans-latin-400-normal.woff2`{.language-sh} into `your_docs/ibm-plex-sans-latin-400-normal.woff2`{.language-sh}.
+
+### Write the CSS
+
+For example, in `your_docs/fonts.css`:
+
+```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');
+}
+
+body {
+  font-family: 'IBM Plex Sans';
+}
+```
+
+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
+
+```sh
+npm install --dev @fontsource/ibm-plex-sans
+```
+
+### Configure Djockey to include the necessary files
+
+In `djockey.yaml`{.language-sh}:
+
+```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
+      patterns:
+        # List all the files you need. Djockey's docs use four different
+        # font weights, so there are a lot.
+        - "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"
+```
+
+That's it, you're done!
+
+## Some nice fonts to use

docs/src/guides/index.djot

@@ -0,0 +1,3 @@
+---
+title: Guides
+---

src/renderers/htmlRenderer.ts

@@ -32,6 +32,7 @@ export class HTMLRenderer implements DjockeyRenderer {
 
   cssURLsRelativeToBase = new Array<string>();
   jsURLsRelativeToBase = new Array<string>();
+  fontURLsRelativeToBase = new Array<string>();
 
   constructor(
     public options: { relativeLinks: boolean } = { relativeLinks: false }
@@ -139,6 +140,11 @@ export class HTMLRenderer implements DjockeyRenderer {
       allStaticFileRelativeRefPaths,
       "**/*.js"
     );
+
+    this.fontURLsRelativeToBase = micromatch.match(
+      allStaticFileRelativeRefPaths,
+      "**/*.woff2"
+    );
   }
 
   async writeDoc(args: {
@@ -193,6 +199,7 @@ export class HTMLRenderer implements DjockeyRenderer {
       urlLists: {
         css: this.cssURLsRelativeToBase.map((path_) => `${baseURL}${path_}`),
         js: this.jsURLsRelativeToBase.map((path_) => `${baseURL}${path_}`),
+        font: this.fontURLsRelativeToBase.map((path_) => `${baseURL}${path_}`),
       },
     });
 

templates/html/base.njk

@@ -5,6 +5,11 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    {% for fontURL in urlLists.font %}
+    <link rel="preload" href="{{ fontURL }}" as="font" type="font/woff2">
+    {% endfor %}
+
     {% for cssURL in urlLists.css %}
       {%- if cssURL.endsWith('.light.css') -%}
       <link rel="stylesheet"  media="(prefers-color-scheme: light)" href="{{ cssURL }}">
@@ -14,6 +19,7 @@
       <link rel="stylesheet" href="{{ cssURL }}">
       {%- endif %}
     {% endfor %}
+
     <title>{{ config.site_name }} - {{ doc.title }}</title>
 
     <meta property="og:type" content="website">