perf: Replace Font Awesome with inline svg icons (#890)

* perf: Replace Font Awesome with inline svg icons

Font Awesome shipped 137 kB of css and eight webfont files for seven
glyphs: the external-link arrow, the search magnifier, the glossary
link icon and four social icons in the footer. Those are inline svgs
now (path data from Font Awesome Free 6.2.1, CC BY 4.0, attributed in
ui/NOTICE), sized and colored via a small .svg-icon utility class.

site.css shrinks from 146 kB to 48 kB and the webfonts/ directory
disappears from the bundle. The fa-* checklist selectors in doc.css
stay: they come from upstream and draw the check marks with css
content, independent of any icon font.

Also removes the inlineDynamicImports rollup option (vite 8 warns it
is redundant for non-code-split builds).

* perf: Serve the svg icons from a sprite instead of inlining them

All seven icons live as symbols in img/icons.svg; usage sites reference
them with <use>, which keeps the markup readable and the path data in
one reusable, cacheable place. currentColor inheritance works through
<use>, so the .svg-icon styling is unchanged. Antora relativizes the
root-relative sprite url in page content, so the external-link-icon
attribute works from any page depth.

The universal-nav partials keep their own pre-existing inline svgs;
they can move into the sprite when that area is next touched.

Author: lfrancke

antora-playbook.yml

@@ -329,7 +329,7 @@ asciidoc:
   attributes:
     base-repo: https://github.com/stackabletech
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
-    external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
+    external-link-icon: "<svg class=\"svg-icon\" style=\"width: 0.75em; height: 0.75em; margin-left: 3px;\" aria-hidden=\"true\"><use href=\"/_/img/icons.svg#icon-external-link\"/></svg>"
 # the default caching directory is ./.cache/antora
 # Antora caches the git repos, this can sometimes lead to stale content
 # use 'make clean' to remove the build and cache directory

local-antora-playbook.yml

@@ -314,7 +314,7 @@ asciidoc:
   attributes:
     base-repo: https://github.com/stackabletech
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
-    external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
+    external-link-icon: "<svg class=\"svg-icon\" style=\"width: 0.75em; height: 0.75em; margin-left: 3px;\" aria-hidden=\"true\"><use href=\"/_/img/icons.svg#icon-external-link\"/></svg>"
 # the default caching directory is ./.cache/antora
 # Antora caches the git repos, this can sometimes lead to stale content
 # use 'make clean' to remove the build and cache directory

modules/reference/pages/glossary.adoc

@@ -1,5 +1,5 @@
 = Glossary
-:li: pass:[<i class="fa-solid fa-link fa-sm" style="margin-left: 5px; vertical-align: baseline;"></i>]
+:li: pass:[<svg class="svg-icon" style="width: 0.875em; height: 0.875em; margin-left: 5px;" aria-hidden="true"><use href="/_/img/icons.svg#icon-link"/></svg>]
 :description: Glossary of Stackable terms, including Role, Role Group, and Stacklet, with definitions and links to detailed explanations.
 
 // refined styling for the glossary

only-dev-antora-playbook.yml

@@ -107,7 +107,7 @@ asciidoc:
   attributes:
     base-repo: https://github.com/stackabletech
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
-    external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
+    external-link-icon: "<svg class=\"svg-icon\" style=\"width: 0.75em; height: 0.75em; margin-left: 3px;\" aria-hidden=\"true\"><use href=\"/_/img/icons.svg#icon-external-link\"/></svg>"
 # the default caching directory is ./.cache/antora
 # Antora caches the git repos, this can sometimes lead to stale content
 # use 'make clean' to remove the build and cache directory

supplemental-ui/partials/navbar.hbs

@@ -18,7 +18,7 @@
         <a class="navbar-item" href="{{{ relativize (versioned "home" page "reference/index.html") }}}">CRD Reference</a>
         {{else}}
         <a class="navbar-item" href="{{{ page.attributes.crd-docs }}}" target="_blank">
-            CRD Reference <i class="fa-solid fa-arrow-up-right-from-square fa-sm" style="margin-left: 5px;"></i>
+            CRD Reference <svg class="svg-icon" style="width: 0.875em; height: 0.875em; margin-left: 5px;" aria-hidden="true"><use href="{{{uiRootPath}}}/img/icons.svg#icon-external-link"/></svg>
         </a>
         {{/if}}
         <hr class="navbar-divider">
@@ -95,13 +95,13 @@
     <a class="navbar-link" href="#">Community</a>
     <div class="navbar-dropdown">
         <a class="navbar-item" href="https://stackable.tech/en/" target="_blank">
-            Homepage <i class="fa-solid fa-arrow-up-right-from-square fa-sm" style="margin-left: 5px;"></i>
+            Homepage <svg class="svg-icon" style="width: 0.875em; height: 0.875em; margin-left: 5px;" aria-hidden="true"><use href="{{{uiRootPath}}}/img/icons.svg#icon-external-link"/></svg>
         </a>
         <a class="navbar-item" href="https://github.com/stackabletech/" target="_blank">
-            GitHub <i class="fa-solid fa-arrow-up-right-from-square fa-sm" style="margin-left: 5px;"></i>
+            GitHub <svg class="svg-icon" style="width: 0.875em; height: 0.875em; margin-left: 5px;" aria-hidden="true"><use href="{{{uiRootPath}}}/img/icons.svg#icon-external-link"/></svg>
         </a>
         <a class="navbar-item" href="https://discord.com/invite/7kZ3BNnCAF" target="_blank">
-            Discord <i class="fa-solid fa-arrow-up-right-from-square fa-sm" style="margin-left: 5px;"></i>
+            Discord <svg class="svg-icon" style="width: 0.875em; height: 0.875em; margin-left: 5px;" aria-hidden="true"><use href="{{{uiRootPath}}}/img/icons.svg#icon-external-link"/></svg>
         </a>
         <hr class="navbar-divider">
         <a class="navbar-item" href="{{{ relativize (versioned "home" page "contributor/index.html") }}}">Contributing</a>

truly-local-playbook.yml

@@ -72,7 +72,7 @@ asciidoc:
   attributes:
     base-repo: https://github.com/stackabletech
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
-    external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
+    external-link-icon: "<svg class=\"svg-icon\" style=\"width: 0.75em; height: 0.75em; margin-left: 3px;\" aria-hidden=\"true\"><use href=\"/_/img/icons.svg#icon-external-link\"/></svg>"
 # the default caching directory is ./.cache/antora
 # Antora caches the git repos, this can sometimes lead to stale content
 # use 'make clean' to remove the build and cache directory

ui/NOTICE

@@ -9,8 +9,8 @@ header comments; this file preserves the attributions and is included
 in the published bundle.
 
 - Font Awesome Free 6.2.1 (https://fontawesome.com)
-  Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License
-  https://fontawesome.com/license/free
+  The inline svg icon path data is derived from Font Awesome Free icons
+  (CC BY 4.0). https://fontawesome.com/license/free
 - highlight.js (https://highlightjs.org)
   BSD 3-Clause License, (c) 2006 Ivan Sagalaev and contributors
 - Asciidoctor Tabs (https://github.com/asciidoctor/asciidoctor-tabs)

ui/build.mjs

@@ -1,5 +1,5 @@
 // Builds the Antora UI bundle (https://docs.antora.org/antora-ui-default/):
-// css/, js/, js/vendor/, font/, webfonts/, img/, helpers/, layouts/, partials/
+// css/, js/, js/vendor/, font/, img/, helpers/, layouts/, partials/
 // zipped as build/ui-bundle.zip (the path the playbooks reference).
 //
 // The scripts are consumed as classic <script src> tags, so every js entry is
@@ -68,8 +68,7 @@ for (const entry of jsEntries) {
           input: entry.input,
           output: {
             format: 'iife',
-            entryFileNames: `js/${entry.name}.js`,
-            inlineDynamicImports: true
+            entryFileNames: `js/${entry.name}.js`
           }
         }
       }
@@ -89,7 +88,6 @@ await build(
           assetFileNames: (asset) => {
             const name = asset.names[0] ?? '';
             if (name === 'site.css') return 'css/site.css';
-            if (/^fa-.+\.(woff2?|ttf)$/.test(name)) return 'webfonts/[name][extname]';
             if (/\.(woff2?|ttf)$/.test(name)) return 'font/[name][extname]';
             if (/\.(svg|png|gif|ico|jpg)$/.test(name)) return 'img/[name][extname]';
             return 'css/[name][extname]';
@@ -100,9 +98,7 @@ await build(
   })
 );
 
-// webfonts/ ships as-is: the Font Awesome css references it with
-// runtime-relative urls that vite cannot (and must not) rewrite
-for (const dir of ['helpers', 'layouts', 'partials', 'img', 'webfonts']) {
+for (const dir of ['helpers', 'layouts', 'partials', 'img']) {
   cpSync(resolve(src, dir), resolve(staged, dir), { recursive: true });
 }
 for (const file of ['NOTICE', 'LICENSE']) {

ui/src/css/base.css

@@ -148,3 +148,13 @@ body ::-webkit-scrollbar-thumb {
 .justify-between {
   justify-content: space-between;
 }
+
+/* Inline svg icons; the path data comes from Font Awesome Free (CC BY 4.0,
+ * see ../../NOTICE). Sizes deviating from 1em are set inline at the usage. */
+.svg-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  fill: currentcolor;
+  vertical-align: -0.125em;
+}

ui/src/css/site.css

@@ -19,6 +19,5 @@
 @import "admonition.css";
 @import "end-of-life-banner.css";
 @import "link-bar.css";
-@import "vendor/fontawesome.css";
 @import "@asciidoctor/tabs/dist/css/tabs.css";
 @import "tabs.css";