better font handling

Author: jsneedles

README.md

@@ -42,6 +42,19 @@ requires all 148 original routes to exist or redirect to a native page. It check
 old anchors, internal links, assets, external-link attributes, and Markdown
 exports, and writes `migration-report.json`. CI runs this complete-site gate.
 
+## Fonts
+
+IBM Plex Sans and Mono are configured through Astro's built-in Fontsource provider
+in `astro.config.mjs`. Astro downloads and caches fonts during the build, then
+serves fingerprinted WOFF2 files from `/_astro/fonts/` with immutable caching.
+Visitors make no Google Fonts requests. The font license is in
+`public/assets/fonts/OFL.txt`.
+
+`<Font />` supplies font-face declarations and adjusted fallbacks. Only the normal
+Latin Sans face is preloaded; other subsets, italics, and Mono load as needed.
+Docs and OG cards share the same self-hosted Sans font. New/uncached font builds
+need network access to Fontsource; rendering the deployed site does not.
+
 ## Page prefetching
 
 `src/scripts/prefetch.ts` warms internal HTML pages on hover, focus, or pointer down
@@ -66,7 +79,7 @@ and inspect imports to find large dependencies. Compression sizes are estimates,
 not measured Cloudflare transfers.
 
 Reports are ignored by Git and stay outside `dist`, so they are never deployed.
-Normal builds do not run the analyzer. Google Fonts, runtime-loaded Pagefind
+Normal builds do not run the analyzer. Font files, runtime-loaded Pagefind
 assets, and copied public assets need separate browser network measurements.
 
 ## Page titles

astro.config.mjs

@@ -1,4 +1,4 @@
-import { defineConfig } from 'astro/config';
+import { defineConfig, fontProviders } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import tailwindcss from '@tailwindcss/vite';
 import navigation from './src/navigation.mjs';
@@ -11,6 +11,22 @@ import bundleAnalysis from './scripts/bundle-analysis.mjs';
 export default defineConfig({
   site: process.env.DOCS_ORIGIN || 'http://localhost:4321',
   output: 'static',
+  fonts: [
+    {
+      provider: fontProviders.fontsource(), name: 'IBM Plex Sans',
+      cssVariable: '--font-ibm-plex-sans', weights: ['100 700'],
+      styles: ['normal', 'italic'],
+      subsets: ['latin', 'latin-ext', 'cyrillic', 'cyrillic-ext', 'greek', 'vietnamese'],
+      formats: ['woff2'], display: 'swap',
+    },
+    {
+      provider: fontProviders.fontsource(), name: 'IBM Plex Mono',
+      cssVariable: '--font-ibm-plex-mono', weights: [400, 500, 600, 700],
+      styles: ['normal', 'italic'],
+      subsets: ['latin', 'latin-ext', 'cyrillic', 'cyrillic-ext', 'vietnamese'],
+      formats: ['woff2'], display: 'swap', fallbacks: ['monospace'],
+    },
+  ],
   // Our fetch-based prefetch matches ClientRouter's request and Vary: Accept.
   // Native link-prefetch requests use a different browser cache variant.
   prefetch: false,

public/_headers

@@ -13,3 +13,7 @@ https://:version.:worker.:account.workers.dev/*
 # Generated OG rendering pages are never indexed, including in production.
 /_og/*
   X-Robots-Tag: noindex, nofollow
+
+# Astro fingerprints these font files; changed fonts receive new URLs.
+/_astro/fonts/*
+  Cache-Control: public, max-age=31536000, immutable

public/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

src/components/Breadcrumbs.astro

@@ -11,7 +11,7 @@ const crumbs = breadcrumbs(route, entry.data.page_title ?? entry.data.title, Boo
   </ol>
 </nav>}
 <style>
-  .breadcrumbs { margin-bottom:.5rem; font-size:.8rem; color:var(--sl-color-gray-3); }
+  .breadcrumbs { margin-bottom:0; font-size:.8rem; color:var(--sl-color-gray-3); }
   ol { display:flex; flex-wrap:wrap; align-items:baseline; gap:.35rem .5rem; list-style:none; padding:0; margin:0; }
   li { display:flex; align-items:baseline; gap:.5rem; min-width:0; max-width:100%; }
   li + li::before { content:'›'; color:var(--sl-color-gray-3); }

src/components/Head.astro

@@ -1,5 +1,6 @@
 ---
 import pages from '../generated/pages.json';
+import { Font } from 'astro:assets';
 import { ClientRouter } from 'astro:transitions';
 import NavigationLifecycle from './NavigationLifecycle.astro';
 import { structuredData, serializeStructuredData } from '../lib/structured-data.mjs';
@@ -18,21 +19,22 @@ const siteTitle = 'HTML/CSS to Image API Docs';
 const brandedTitle = (title: string) => title === siteTitle || title.endsWith(` | ${siteTitle}`)
   ? title : `${title} | ${siteTitle}`;
 const tags = head.filter(tag => tag.tag !== 'title' &&
+  !(tag.tag === 'meta' && tag.attrs?.charset) &&
   !(tag.tag === 'meta' && tag.attrs?.name === 'generator'))
   .map(tag => tag.tag === 'meta' &&
     (tag.attrs?.property === 'og:title' || tag.attrs?.name === 'twitter:title')
     ? { ...tag, attrs: { ...tag.attrs, content: brandedTitle(entry.data.og_title ?? entry.data.title) } }
     : tag);
 ---
+<meta charset="utf-8" />
 <title>{brandedTitle(entry.data.title)}</title>
 <ClientRouter fallback="swap" />
 <NavigationLifecycle />
 {jsonLd && <script type="application/ld+json" set:html={serializeStructuredData(jsonLd)} />}
 {entry.data.changelog && <meta property="article:published_time" content={entry.data.changelog.date} />}
 <meta data-pagefind-filter="kind[content]" content={entry.data.changelog ? 'changelog' : 'docs'} />
-<link rel="preconnect" href="https://fonts.googleapis.com" />
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;0,700;1,400&family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400;1,600&display=swap" />
+<Font cssVariable="--font-ibm-plex-sans" preload={[{ subset: 'latin', style: 'normal' }]} />
+<Font cssVariable="--font-ibm-plex-mono" />
 {tags.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
 {!tags.some(tag => tag.tag === 'meta' && tag.attrs?.name === 'twitter:title') &&
   <meta name="twitter:title" content={brandedTitle(entry.data.og_title ?? entry.data.title)} />}

src/components/PageActions.astro

@@ -4,7 +4,7 @@ const pageUrl = new URL(Astro.url.pathname, Astro.site || Astro.url.origin).href
 const prompt = `Read from ${pageUrl} so I can ask questions about it.`;
 ---
 <details class="page-actions" data-pagefind-ignore>
-  <summary aria-label="Page actions"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><rect x="8" y="8" width="12" height="13" rx="2"/><path d="M16 8V3H3v13h5"/></svg> Copy page <span aria-hidden="true">⌄</span></summary>
+  <summary aria-label="Copy page and more options"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><rect x="8" y="8" width="12" height="13" rx="2"/><path d="M16 8V3H3v13h5"/></svg> Copy page <svg class="block shrink-0" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m7 9.5 5 5 5-5" /></svg></summary>
   <div class="action-list">
     <button type="button" data-copy-page={markdownPath}><strong>Copy page</strong><small>Copy Markdown for LLMs</small></button>
     <a href={markdownPath} data-astro-reload><strong>View as Markdown ↗</strong><small>Read this page as plain text</small></a>
@@ -42,7 +42,7 @@ const prompt = `Read from ${pageUrl} so I can ask questions about it.`;
   document.addEventListener('astro:page-load', initializePageActions);
 </script>
 <style>
-  .page-actions { position:relative; flex-shrink:0; margin-top:.45rem; font-size:.8rem; z-index:10; }
+  .page-actions { position:relative; flex-shrink:0; margin-top:0; font-size:.8rem; z-index:10; }
   summary { display:flex; align-items:center; gap:.5rem; list-style:none; border:1px solid var(--sl-color-gray-5); padding:.5rem .7rem; border-radius:.35rem; cursor:pointer; color:var(--sl-color-gray-2); white-space:nowrap; }
   summary::-webkit-details-marker { display:none; }
   summary:hover { background:var(--sl-color-bg-sidebar); }

src/components/PageTitle.astro

@@ -7,16 +7,18 @@ const pageTitle = entry.data.page_title ?? entry.data.title;
 const route = Astro.url.pathname;
 const markdownPath = route === '/' ? '/index.md' : `${route.replace(/\/$/, '')}.md`;
 ---
-<Breadcrumbs />
-<div class="page-heading">
-  {entry.data.page_title ? <h1 id="_top">{pageTitle}</h1> : <DefaultPageTitle />}
-  {entry.id !== '404' && <PageActions markdownPath={markdownPath} title={pageTitle} />}
+<div class="page-heading grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-4 gap-y-2">
+  {route !== '/' && <div class="col-start-1 row-start-1 min-w-0 min-[40rem]:col-span-2"><Breadcrumbs /></div>}
+  <div class="col-span-2 col-start-1 row-start-2 min-w-0 min-[40rem]:col-span-1">
+    {entry.data.page_title ? <h1 id="_top">{pageTitle}</h1> : <DefaultPageTitle />}
+  </div>
+  {entry.id !== '404' && <div class="col-start-2 row-start-1 self-start justify-self-end min-[40rem]:row-start-2 min-[40rem]:self-center"><PageActions markdownPath={markdownPath} title={pageTitle} /></div>}
 </div>
 {entry.data.changelog && <p class="published"><time data-changelog-date datetime={entry.data.changelog.date}>{new Date(`${entry.data.changelog.date}T00:00:00Z`).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' })}</time></p>}
 <style>
   h1 { margin-top:1rem; font-size:var(--sl-text-h1); line-height:var(--sl-line-height-headings); font-weight:600; color:var(--sl-color-white); }
   .published { margin:.8rem 0 0; font-size:.9rem; color:var(--sl-color-gray-3); }
-  .page-heading { display:flex; align-items:center; gap:1rem; justify-content:space-between; margin-top:.5rem; }
+  .page-heading { margin-top:.5rem; }
   .page-heading :global(h1) { min-width:0; margin-top:0; }
-  @media(max-width:40rem) { .page-heading { flex-wrap:wrap; } }
+
 </style>

src/components/SiteTitle.astro

@@ -1,4 +1,4 @@
-<a href="/" class="brand" aria-label="HTML/CSS to Image documentation home">
+<a href="/" class="brand" aria-label="HTML/CSS to Image Docs home">
   <img src="/assets/images/hcti-logo.svg" width="50" height="50" alt="HTML/CSS to Image" />
   <span>Docs</span>
 </a>

src/pages/[...og].astro

@@ -1,5 +1,6 @@
 ---
 import pages from '../generated/pages.json';
+import { Font } from 'astro:assets';
 // Astro ignores underscore-prefixed page folders. Generate only these internal
 // /_og/<hash>/ routes explicitly instead.
 export function getStaticPaths() {
@@ -23,9 +24,7 @@ const gradient = `linear-gradient(${angle}deg,${colors[0]} 0%,${colors[1]} 48%,$
 ---
 <!doctype html>
 <html lang="en"><head><meta charset="utf-8" /><meta name="robots" content="noindex" /><title>{card.title}</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com" />
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;600;700&display=block" />
+  <Font cssVariable="--font-ibm-plex-sans" preload={[{ subset: 'latin', style: 'normal' }]} />
 </head>
 <body data-pagefind-ignore>
   <main id="og-card" style={{ background: gradient }}>
@@ -41,7 +40,7 @@ const gradient = `linear-gradient(${angle}deg,${colors[0]} 0%,${colors[1]} 48%,$
 </body></html>
 <style>
   * { box-sizing:border-box; }
-  body { margin:0; font-family:'IBM Plex Sans',sans-serif; }
+  body { margin:0; font-family:var(--font-ibm-plex-sans); }
   #og-card { width:1200px; height:630px; padding:32px; color:#192521; }
   .panel { height:100%; padding:38px 48px 32px; display:flex; flex-direction:column; border:1px solid #dfe8e2; border-radius:8px; background-color:#fcfdfc; background-image:linear-gradient(#254d3a0a 1px,transparent 1px),linear-gradient(90deg,#254d3a0a 1px,transparent 1px); background-size:64px 64px; background-position:26px 26px; box-shadow:0 12px 32px #18382d30; }
   .brand { display:flex; align-items:center; gap:14px; font-weight:600; font-size:24px; letter-spacing:-.5px; }