From ba69bb265bd8f9a98dac0be956eb192717ac6b06 Mon Sep 17 00:00:00 2001 From: Steve Landey Date: Sat, 7 Sep 2024 08:52:20 -0700 Subject: [PATCH] Font preloading. Guide to custom fonts. --- docs/src/changelog.dj | 1 + docs/src/features/asides.dj | 10 +-- docs/src/foundations/static_files.dj | 20 ++++- docs/src/guides/custom_fonts.dj | 75 +++++++++++++++++++ docs/src/{foundations => guides}/deploying.dj | 0 docs/src/guides/index.djot | 3 + src/renderers/htmlRenderer.ts | 7 ++ templates/html/base.njk | 6 ++ 8 files changed, 115 insertions(+), 7 deletions(-) create mode 100644 docs/src/guides/custom_fonts.dj rename docs/src/{foundations => guides}/deploying.dj (100%) create mode 100644 docs/src/guides/index.djot diff --git a/docs/src/changelog.dj b/docs/src/changelog.dj index 4699e34..07ee549 100644 --- a/docs/src/changelog.dj +++ b/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 diff --git a/docs/src/features/asides.dj b/docs/src/features/asides.dj index cb240cd..b31e9b3 100644 --- a/docs/src/features/asides.dj +++ b/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 diff --git a/docs/src/foundations/static_files.dj b/docs/src/foundations/static_files.dj index 441d013..cf75221 100644 --- a/docs/src/foundations/static_files.dj +++ b/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 ``{.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. \ No newline at end of file diff --git a/docs/src/guides/custom_fonts.dj b/docs/src/guides/custom_fonts.dj new file mode 100644 index 0000000..d00f29c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/src/foundations/deploying.dj b/docs/src/guides/deploying.dj similarity index 100% rename from docs/src/foundations/deploying.dj rename to docs/src/guides/deploying.dj diff --git a/docs/src/guides/index.djot b/docs/src/guides/index.djot new file mode 100644 index 0000000..9d18d4d --- /dev/null +++ b/docs/src/guides/index.djot @@ -0,0 +1,3 @@ +--- +title: Guides +--- \ No newline at end of file diff --git a/src/renderers/htmlRenderer.ts b/src/renderers/htmlRenderer.ts index 5705b70..abf5f64 100644 --- a/src/renderers/htmlRenderer.ts +++ b/src/renderers/htmlRenderer.ts @@ -32,6 +32,7 @@ export class HTMLRenderer implements DjockeyRenderer { cssURLsRelativeToBase = new Array(); jsURLsRelativeToBase = new Array(); + fontURLsRelativeToBase = new Array(); 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_}`), }, }); diff --git a/templates/html/base.njk b/templates/html/base.njk index 14c8517..392af88 100644 --- a/templates/html/base.njk +++ b/templates/html/base.njk @@ -5,6 +5,11 @@ + + {% for fontURL in urlLists.font %} + + {% endfor %} + {% for cssURL in urlLists.css %} {%- if cssURL.endsWith('.light.css') -%} @@ -14,6 +19,7 @@ {%- endif %} {% endfor %} + {{ config.site_name }} - {{ doc.title }}