@glossarist/concept-browser 0.7.108 → 0.7.109

package/README.md

@@ -235,22 +235,33 @@ Then in `site-config.yml`:
 branding:
   favicon:
     base_path: /                              # URL prefix (BASE_PATH-aware; default '/')
-    skip_default_links: true                  # suppress the default <link> block
     source_dir: assets/favicons               # canonical files (all of them, in one directory)
-    links_html: |-                            # raw HTML emitted verbatim in <head>
-      <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
-      <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-      <link rel="shortcut icon" href="/favicon.ico" />
-      <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
-      <link rel="manifest" href="/site.webmanifest" />
+    icons:                                    # DATA — declare each icon, not HTML
+      - rel: icon
+        type: image/svg+xml
+        href: favicon.svg
+      - rel: icon
+        type: image/png
+        sizes: 96x96
+        href: favicon-96x96.png
+      - rel: shortcut icon
+        href: favicon.ico
+      - rel: apple-touch-icon
+        sizes: 180x180
+        href: apple-touch-icon.png
+      - rel: manifest
+        href: site.webmanifest
 ```
 
+The CLI copies every file from `source_dir/` into `public/` (also removing the default cruft), then renders one `<link>` tag per icon entry. The `href` is a **filename** — the system applies the correct `base_path` prefix automatically. Absolute URLs (`https://cdn.example.com/x.png`) and root-relative paths (`/x.png`) are emitted unchanged.
+
 | Field | Type | Effect |
 |---|---|---|
 | `source_dir` | string | Path (relative to cwd) to a directory containing **all** canonical favicon files. The CLI copies every file in this directory into `public/`, overriding any defaults. Also removes the default-generated cruft (`apple-touch-icon-57x57.png`, `favicon-16x16.png`, etc.) so it doesn't linger. |
-| `links_html` | string | Raw HTML (one or more `<link>` tags) emitted verbatim in `<head>`. Use this to declare which of the source_dir files the browser should load, with what `sizes`/`type`. |
-| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `links_html` and `source_dir` for fully custom branding. |
+| `icons` | `FaviconIcon[]` | **DATA — recommended.** Array of `{ rel, href, type?, sizes? }` entries. Each renders to one `<link>` tag with BASE_PATH-aware href. Replaces the default 16-link set. |
+| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `icons` and `source_dir` for fully custom branding. |
 | `base_path` | string | URL prefix prepended to every emitted link. Useful for BASE_PATH-scoped deployments (e.g. `/vocab/`). |
+| ~~`links_html`~~ | string | **@deprecated** — use `icons` instead. Raw HTML emitted verbatim. Impossible to validate or safely BASE_PATH-rewrite; kept for backward compat with a console warning. |
 
 The object form exists so consumers with a RealFaviconGenerator favicon set (or any other canonical brand favicon bundle) can install it without a post-build script. Previously this required workarounds like `glossarist/cie-eilv/scripts/install-favicons.mjs` (149 lines) and `glossarist/iala-vocab/scripts/install-favicons.mjs` (175 lines) — both are now unnecessary.
 

package/cli/index.mjs

@@ -97,9 +97,12 @@ Environment:
     //      package generates the full variant set from it.
     //
     //   2. Object — `{ source_dir?, links_html?, skip_default_links?, base_path? }`.
-    //      - `links_html`: raw HTML (one or more <link> tags) emitted verbatim.
-    //        Skips the `favicons` package entirely; consumer is responsible
-    //        for providing the actual icon files in public/.
+    //      - `icons`: DATA — array of { rel, href, type?, sizes? } entries.
+    //        The hrefs are filenames; the CLI applies BASE_PATH and renders
+    //        well-formed <link> tags. Recommended over `links_html`.
+    //      - `links_html` (deprecated): raw HTML emitted verbatim.
+    //        Skips the `favicons` package entirely; impossible to validate
+    //        or safely BASE_PATH-rewrite. Use `icons` instead.
     //      - `source_dir`: directory of canonical favicon files copied as-is
     //        into public/ (overriding any defaults). Useful when the consumer
     //        already has a RealFaviconGenerator output set.
@@ -114,8 +117,34 @@ Environment:
 
     if (faviconCfgIsObject) {
       // Object form — honor each declared field.
+      if (faviconCfg.icons && Array.isArray(faviconCfg.icons) && faviconCfg.icons.length > 0) {
+        // Data-driven: build <link> tags from the icons array.
+        const basePathForIcons =
+          faviconCfg.base_path ||
+          process.env.BASE_PATH?.replace(/\/+$/, '') ||
+          '';
+        faviconHtml = faviconCfg.icons.map((icon) => {
+          const attrs = [`rel="${icon.rel || 'icon'}"`];
+          if (icon.type) attrs.push(`type="${icon.type}"`);
+          if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+          // Bare filenames get BASE_PATH-prefixed; absolute URLs / root-relative
+          // paths are emitted as-is.
+          let href = icon.href || '';
+          if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+            href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+          }
+          attrs.push(`href="${href}"`);
+          return `<link ${attrs.join(' ')} />`;
+        }).join('\n    ');
+        skipDefaultGeneration = true;
+      }
       if (faviconCfg.links_html) {
-        faviconHtml = String(faviconCfg.links_html);
+        if (faviconHtml) {
+          console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+        } else {
+          console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+          faviconHtml = String(faviconCfg.links_html);
+        }
         skipDefaultGeneration = true;
       }
       if (faviconCfg.source_dir) {

package/cli/index.ts

@@ -66,19 +66,23 @@ interface BrandingFonts {
   weights?: number[];
 }
 
+interface FaviconIcon {
+  rel?: string;
+  href: string;
+  type?: string;
+  sizes?: string;
+}
+
 interface FaviconConfig {
-  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
-   *  when deploying under BASE_PATH != '/'. */
+  /** Path prefix for all favicon URLs. Defaults to BASE_PATH-aware '/'. */
   base_path?: string;
-  /** Skip emitting the default <link rel="icon"> and <link rel="apple-touch-icon">
-   *  tags. Use when the consumer provides their own RFG-compatible markup via
-   *  `links_html`. Default: false (emit default tags). */
+  /** Skip emitting the default <link> block. */
   skip_default_links?: boolean;
-  /** Raw HTML string (one or more <link> tags) to emit in <head> instead of
-   *  the default favicon block. RealFaviconGenerator output goes here. */
+  /** Consumer-declared icons (DATA, not HTML). Replaces the default set. */
+  icons?: FaviconIcon[];
+  /** @deprecated Use `icons` instead. Raw HTML — kept for backward compat. */
   links_html?: string;
-  /** Consumer-side directory (relative to cwd) holding canonical favicon files.
-   *  The CLI copies these into public/, overriding defaults. */
+  /** Consumer-side directory of canonical favicon files. */
   source_dir?: string;
 }
 
@@ -133,8 +137,32 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
 
   if (faviconCfgObject) {
     const cfg: FaviconConfig = faviconCfgObject;
+    if (cfg.icons && cfg.icons.length > 0) {
+      // Data-driven: build <link> tags from the icons array.
+      const basePathForIcons: string =
+        cfg.base_path ||
+        process.env.BASE_PATH?.replace(/\/+$/, '') ||
+        '';
+      faviconHtml = cfg.icons.map((icon: FaviconIcon): string => {
+        const attrs: string[] = [`rel="${icon.rel || 'icon'}"`];
+        if (icon.type) attrs.push(`type="${icon.type}"`);
+        if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+        let href: string = icon.href || '';
+        if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+          href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+        }
+        attrs.push(`href="${href}"`);
+        return `<link ${attrs.join(' ')} />`;
+      }).join('\n    ');
+      skipDefaultGeneration = true;
+    }
     if (cfg.links_html) {
-      faviconHtml = String(cfg.links_html);
+      if (faviconHtml) {
+        console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+      } else {
+        console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+        faviconHtml = String(cfg.links_html);
+      }
       skipDefaultGeneration = true;
     }
     if (cfg.source_dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.108",
+  "version": "0.7.109",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/src/__tests__/utils/favicon-links.test.ts

@@ -1,25 +1,23 @@
 import { describe, it, expect } from 'vitest';
-import { buildDefaultFaviconLinks, renderFaviconLinkTag } from '../../utils/favicon-links';
+import { buildFaviconLinks, renderFaviconLinkTag, type FaviconIcon } from '../../utils/favicon-links';
 
 /**
- * Regression test for the sub-path deployment 404 bug.
+ * Regression test for the sub-path deployment 404 bug + the
+ * data-driven icons API.
  *
- * Bug (filed by user, 2026-08-01): deployments at sub-paths
+ * Bug 1 (filed by user, 2026-08-01): deployments at sub-paths
  * (e.g. `/cie-eilv/`) saw console 404s for `favicon-32x32.png`,
  * `favicon-16x16.png`, `favicon-48x48.png` because the emitted
- * `<link href>` pointed at the ROOT (`/favicon-32x32.png`) instead
- * of the deployment sub-path (`/cie-eilv/favicon-32x32.png`).
+ * `<link href>` pointed at the ROOT instead of the deployment sub-path.
  *
- * Root cause: Default.astro hardcoded `const faviconBase = '/'`.
- * Fix: cascade through configuration sources (favicon-base.ts) and
- * emit links with the resolved prefix.
- *
- * This test exercises the full link-emission path: config in →
- * resolved base → link tags with correct hrefs.
+ * Bug 2 (filed by user, 2026-08-01): the `links_html` field required
+ * consumers to inject raw HTML — impossible to validate, can't be safely
+ * BASE_PATH-rewritten. Refactored to DATA: `icons: [{ rel, href, type?,
+ * sizes? }]` — href is a filename, system applies the correct prefix.
  */
-describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
+describe('buildFaviconLinks — BASE_PATH regression', () => {
   it('emits /-prefixed hrefs for root deployment', () => {
-    const links = buildDefaultFaviconLinks({ astroBaseUrl: '/' });
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
     const png16 = links.find(l => l.sizes === '16x16');
     const png32 = links.find(l => l.sizes === '32x32');
     const png48 = links.find(l => l.sizes === '48x48');
@@ -30,13 +28,9 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
 
   /**
    * THE LOAD-BEARING TEST — pins the exact bug the user reported.
-   *
-   * Reproduction: cie-eilv deployment at /cie-eilv/. The 0.7.106/0.7.107
-   * build emitted href="/favicon-32x32.png" — wrong. The fix must emit
-   * href="/cie-eilv/favicon-32x32.png".
    */
   it('emits /cie-eilv/-prefixed hrefs for sub-path deployment', () => {
-    const links = buildDefaultFaviconLinks({
+    const links = buildFaviconLinks({
       siteConfigBasePath: '/cie-eilv/',
       astroBaseUrl: '/',
     });
@@ -49,24 +43,18 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
   });
 
   it('handles deep sub-paths', () => {
-    const links = buildDefaultFaviconLinks({
-      siteConfigBasePath: '/vocab/iala/',
-    });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/vocab/iala/' });
     const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
     expect(icon?.href).toBe('/vocab/iala/favicon.ico');
   });
 
   it('handles basePath without trailing slash', () => {
-    const links = buildDefaultFaviconLinks({
-      siteConfigBasePath: '/cie-eilv', // no trailing slash
-    });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/cie-eilv' });
     const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
     expect(icon?.href).toBe('/cie-eilv/favicon.ico');
   });
 
   it('never produces a bare "/" href', () => {
-    // Regression guard: a future bug that drops the filename would leave
-    // just the prefix. This test fails loudly if that happens.
     const scenarios = [
       { astroBaseUrl: '/' },
       { astroBaseUrl: '/vocab/' },
@@ -74,7 +62,7 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
       { brandingFaviconBasePath: '/custom/' },
     ];
     for (const input of scenarios) {
-      const links = buildDefaultFaviconLinks(input);
+      const links = buildFaviconLinks(input);
       for (const link of links) {
         expect(link.href, `bare href for input ${JSON.stringify(input)}`).not.toBe('/');
         expect(link.href.length, `empty href for input ${JSON.stringify(input)}`).toBeGreaterThan(1);
@@ -83,14 +71,88 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
   });
 
   it('emits the canonical 16 default favicon tags', () => {
-    const links = buildDefaultFaviconLinks({ astroBaseUrl: '/' });
-    // 5 icons (ico + svg + 3 PNG sizes) + 11 apple-touch-icon sizes = 16
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
     expect(links.length).toBe(16);
     expect(links.filter(l => l.rel === 'icon').length).toBe(5);
     expect(links.filter(l => l.rel === 'apple-touch-icon').length).toBe(11);
   });
 });
 
+describe('buildFaviconLinks — consumer-declared icons (data form)', () => {
+  const consumerIcons: FaviconIcon[] = [
+    { rel: 'icon',          type: 'image/svg+xml', href: 'favicon.svg' },
+    { rel: 'icon',          type: 'image/png',     sizes: '96x96', href: 'favicon-96x96.png' },
+    { rel: 'shortcut icon', href: 'favicon.ico' },
+    { rel: 'apple-touch-icon', sizes: '180x180',  href: 'apple-touch-icon.png' },
+    { rel: 'manifest',      href: 'site.webmanifest' },
+  ];
+
+  it('replaces the default set when icons is non-empty', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    expect(links.length).toBe(consumerIcons.length);
+    // Should NOT contain any of the default 16 links.
+    expect(links.find(l => l.sizes === '16x16')).toBeUndefined();
+    expect(links.find(l => l.sizes === '32x32')).toBeUndefined();
+  });
+
+  it('prefixes bare filenames with the resolved base path', () => {
+    const links = buildFaviconLinks({
+      siteConfigBasePath: '/cie-eilv/',
+      icons: consumerIcons,
+    });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const ico = links.find(l => l.rel === 'shortcut icon');
+    const manifest = links.find(l => l.rel === 'manifest');
+    expect(svg?.href).toBe('/cie-eilv/favicon.svg');
+    expect(png96?.href).toBe('/cie-eilv/favicon-96x96.png');
+    expect(ico?.href).toBe('/cie-eilv/favicon.ico');
+    expect(manifest?.href).toBe('/cie-eilv/site.webmanifest');
+  });
+
+  it('emits absolute URLs as-is (no prefix)', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [
+        { rel: 'icon', type: 'image/svg+xml', href: 'https://cdn.example.com/favicon.svg' },
+        { rel: 'icon', href: 'favicon.ico' },
+      ],
+    });
+    const cdn = links.find(l => l.href.startsWith('https://'));
+    const local = links.find(l => l.href.endsWith('favicon.ico') && !l.href.startsWith('https://'));
+    expect(cdn?.href).toBe('https://cdn.example.com/favicon.svg');
+    expect(local?.href).toBe('/vocab/favicon.ico');
+  });
+
+  it('emits root-relative paths as-is', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [{ rel: 'icon', href: '/absolute-path.png' }],
+    });
+    expect(links[0].href).toBe('/absolute-path.png');
+  });
+
+  it('preserves type and sizes attributes from the data', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const touch = links.find(l => l.rel === 'apple-touch-icon');
+    expect(svg?.type).toBe('image/svg+xml');
+    expect(png96?.sizes).toBe('96x96');
+    expect(touch?.sizes).toBe('180x180');
+  });
+
+  it('falls back to default set when icons is empty array', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: [] });
+    expect(links.length).toBe(16);
+  });
+
+  it('falls back to default set when icons is undefined', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
+    expect(links.length).toBe(16);
+  });
+});
+
 describe('renderFaviconLinkTag', () => {
   it('renders all attributes in deterministic order', () => {
     const html = renderFaviconLinkTag({
@@ -112,8 +174,7 @@ describe('renderFaviconLinkTag', () => {
   });
 
   it('never emits an empty href', () => {
-    // Build a complete link tag and verify the href attribute has content.
-    const links = buildDefaultFaviconLinks({ siteConfigBasePath: '/sub-path/' });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/sub-path/' });
     for (const link of links) {
       const html = renderFaviconLinkTag(link);
       const hrefMatch = html.match(/href="([^"]+)"/);

package/src/config/types.ts

@@ -30,16 +30,31 @@ export interface LogoConfig {
   localDark?: string;
 }
 
+export interface FaviconIcon {
+  /** The `rel` attribute: "icon", "shortcut icon", "apple-touch-icon", "manifest". */
+  rel: string;
+  /** Icon file path. Bare filenames ("favicon.ico") get BASE_PATH-prefixed
+   *  automatically; absolute URLs and root-relative paths are emitted as-is. */
+  href: string;
+  /** Optional MIME type hint (e.g., "image/png", "image/svg+xml"). */
+  type?: string;
+  /** Optional sizes attribute (e.g., "180x180", "any"). */
+  sizes?: string;
+}
+
 export interface FaviconConfig {
-  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
-   *  when deploying under BASE_PATH != '/'. */
+  /** Path prefix for all favicon URLs. Defaults to BASE_PATH-aware '/'. */
   base_path?: string;
-  /** Skip emitting the default <link rel="icon"> and <link rel="apple-touch-icon">
-   *  tags. Use when the consumer provides their own RFG-compatible markup via
-   *  `links_html`. Default: false (emit default tags). */
+  /** Skip emitting the default <link> block. Use when the consumer provides
+   *  their own icons via `icons` or wants zero favicon <link> tags. */
   skip_default_links?: boolean;
-  /** Raw HTML string (one or more <link> tags) to emit in <head> instead of
-   *  the default favicon block. RealFaviconGenerator output goes here. */
+  /** Consumer-declared icons (DATA, not HTML). Replaces the default 16-link
+   *  set when non-empty. Each entry renders to a single <link> tag with
+   *  BASE_PATH-aware href. */
+  icons?: FaviconIcon[];
+  /** @deprecated Use `icons` instead. Raw HTML emitted verbatim — impossible
+   *  to validate, can't be safely BASE_PATH-rewritten. Kept for backward
+   *  compat; emits a console warning when used. */
   links_html?: string;
   /** Consumer-side directory (relative to cwd) holding canonical favicon files.
    *  The CLI's favicon step copies these into public/, overriding defaults. */

package/src/layouts/Default.astro

@@ -52,24 +52,52 @@ const fontHeading = fontStack(headingFont, DEFAULT_CATEGORY.heading) ?? DEFAULT_
 const fontBody = fontStack(brandingFonts?.body, DEFAULT_CATEGORY.body) ?? DEFAULT_FONTS.body;
 const fontMono = fontStack(brandingFonts?.mono, DEFAULT_CATEGORY.mono) ?? DEFAULT_FONTS.mono;
 
-// Favicon configuration (issue #173).
+// Favicon configuration (issues #173, #177, and the data-driven refactor).
 //
-// Consumers provide their own favicon set in one of two ways:
+// Consumers provide their own favicon set in one of these ways:
 //
-//   1. Drop canonical files at `branding.favicon.source_dir` (relative
-//      to the consumer's cwd). The CLI's existing favicon step already
-//      copies these into public/ overriding the defaults — this layout
-//      just needs to emit the right <link> tags.
+//   1. Declare icons as DATA (recommended):
+//        branding:
+//          favicon:
+//            icons:
+//              - rel: icon
+//                type: image/svg+xml
+//                href: favicon.svg
+//              - rel: icon
+//                type: image/png
+//                sizes: 96x96
+//                href: favicon-96x96.png
+//              - rel: shortcut icon
+//                href: favicon.ico
+//              - rel: apple-touch-icon
+//                sizes: 180x180
+//                href: apple-touch-icon.png
+//              - rel: manifest
+//                href: site.webmanifest
+//      The hrefs are filenames (or absolute URLs) — the layout applies
+//      the correct BASE_PATH prefix automatically.
 //
-//   2. Set `branding.favicon.skip_default_links: true` and inject
-//      custom <link> tags via the `branding.favicon.links_html`
-//      string (e.g. RealFaviconGenerator output). The layout emits
-//      that verbatim and skips the default tag block.
+//   2. Drop canonical files at `branding.favicon.source_dir` (relative
+//      to the consumer's cwd). The CLI copies these into public/, and
+//      the layout emits the default 16-link set with BASE_PATH-aware URLs.
 //
-// When neither is set, today's default behavior is preserved.
+//   3. Set `branding.favicon.skip_default_links: true` to emit nothing
+//      (consumer takes full control via their own layout patching).
+//
+// `links_html` is DEPRECATED — raw HTML can't be safely BASE_PATH-rewritten
+// or validated. It still works for backward compat, with a console warning.
 const faviconCfg = siteConfig?.branding?.favicon ?? {};
-const skipDefaultFaviconLinks = faviconCfg.skip_default_links === true;
-const customFaviconLinks: string = faviconCfg.links_html ?? '';
+const faviconCfgIsObject =
+  faviconCfg !== null && typeof faviconCfg === 'object' && !Array.isArray(faviconCfg);
+const skipDefaultFaviconLinks = faviconCfgIsObject && faviconCfg.skip_default_links === true;
+const consumerIcons = faviconCfgIsObject ? (faviconCfg.icons ?? null) : null;
+const deprecatedLinksHtml: string = faviconCfgIsObject ? (faviconCfg.links_html ?? '') : '';
+if (deprecatedLinksHtml) {
+  console.warn(
+    'branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead — ' +
+    'see src/utils/favicon-links.ts for the schema. links_html will be removed in a future release.',
+  );
+}
 
 // BASE_PATH-aware favicon URL prefix. Walks the configuration cascade:
 // branding.favicon.base_path → siteConfig.basePath → import.meta.env.BASE_URL → '/'.
@@ -83,17 +111,22 @@ const faviconBaseInput = {
   astroBaseUrl: import.meta.env.BASE_URL,
 };
 const faviconBase = resolveFaviconBase(faviconBaseInput);
-const faviconLinks = buildDefaultFaviconLinks(faviconBaseInput).map(renderFaviconLinkTag);
+// Build the favicon <link> block from data (consumer-declared icons or
+// the default 16-link set). BASE_PATH is applied to every href.
+const faviconLinks = buildFaviconLinks({
+  ...faviconBaseInput,
+  icons: consumerIcons ?? undefined,
+}).map(renderFaviconLinkTag);
 ---
 
 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
-    {!skipDefaultFaviconLinks && (
+    {!skipDefaultFaviconLinks && faviconLinks.length > 0 && (
       <Fragment set:html={faviconLinks.join('\n    ')} />
     )}
-    {customFaviconLinks && <Fragment set:html={customFaviconLinks} />}
+    {deprecatedLinksHtml && <Fragment set:html={deprecatedLinksHtml} />}
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
     <meta name="apple-mobile-web-app-title" content={siteConfig.title} />

package/src/utils/favicon-links.ts

@@ -4,16 +4,39 @@
  *
  * Used by:
  *   - `src/layouts/Default.astro` (build-time SSG)
+ *   - `cli/index.mjs`             (consumer-side favicon pipeline)
  *
- * Why this exists: a deployment at `/cie-eilv/` has its favicon files
- * at `/cie-eilv/favicon.ico`, NOT `/favicon.ico`. Hardcoding `/` as
- * the URL prefix (which 0.7.106 did) caused 404s on every sub-path
- * deployment. This builder walks the configuration cascade via
- * `resolveFaviconBase` and emits correctly-prefixed link tags.
+ * Design principle: declare icons as DATA, not HTML. Consumers describe
+ * their favicon set via `branding.favicon.icons: [{ rel, href, type?,
+ * sizes? }]`. The href is a filename (or path relative to the deployment
+ * root); the system applies the correct BASE_PATH prefix and renders
+ * well-formed `<link>` tags. No raw HTML in YAML.
+ *
+ * Why data over HTML: HTML-in-YAML is impossible to validate, can't be
+ * BASE_PATH-rewritten safely (regex on user-supplied markup is brittle),
+ * and forces the consumer to know the exact attribute order/shape the
+ * browser expects. Data lets us validate, normalize, and render.
  */
 
 import { resolveFaviconBase } from './favicon-base';
 
+export interface FaviconIcon {
+  /** The `rel` attribute. Most common: "icon", "shortcut icon",
+   *  "apple-touch-icon", "manifest". */
+  rel: string;
+  /** The icon file path. May be either:
+   *  - A bare filename ("favicon.ico") — gets prefixed with the resolved
+   *    base path automatically.
+   *  - An absolute URL ("https://...") or root-relative path ("/x.png")
+   *    — emitted as-is, no prefixing.
+   */
+  href: string;
+  /** Optional MIME type hint. */
+  type?: string;
+  /** Optional `sizes` attribute (e.g., "180x180", "any"). */
+  sizes?: string;
+}
+
 export interface FaviconLinkTag {
   rel: string;
   type?: string;
@@ -21,8 +44,9 @@ export interface FaviconLinkTag {
   href: string;
 }
 
-/** Default favicon file set emitted by the CLI's `favicons` pipeline. */
-const DEFAULT_FAVICON_FILES: readonly FaviconLinkTag[] = [
+/** Default favicon file set emitted by the CLI's `favicons` pipeline.
+ *  Used when the consumer doesn't declare `branding.favicon.icons`. */
+const DEFAULT_FAVICON_FILES: readonly FaviconIcon[] = [
   { rel: 'icon',       type: 'image/x-icon',  href: 'favicon.ico' },
   { rel: 'icon',       type: 'image/svg+xml', href: 'favicon.svg' },
   { rel: 'icon',       type: 'image/png',     sizes: '16x16',  href: 'favicon-16x16.png' },
@@ -48,22 +72,47 @@ export interface BuildFaviconLinksInput {
   siteConfigBasePath?: string;
   /** Build-time BASE_PATH from Astro/Vite (`import.meta.env.BASE_URL`). */
   astroBaseUrl?: string;
+  /** Consumer-declared icons. When set, replaces the default set. */
+  icons?: readonly FaviconIcon[];
 }
 
 /**
- * Build the list of default favicon link tags with BASE_PATH-aware URLs.
+ * Build the list of favicon link tags with BASE_PATH-aware URLs.
  *
- * Returns the tag descriptors; the caller (Default.astro) renders them
- * into <link> elements.
+ * - If `input.icons` is provided (non-empty), uses that set; otherwise
+ *   falls back to the default 16-link set.
+ * - For each icon, the href is normalized:
+ *   - Filenames ("favicon.ico") → prefixed with the resolved base path.
+ *   - Absolute URLs ("https://...") → emitted as-is.
+ *   - Root-relative paths ("/x.png") → emitted as-is.
  */
-export function buildDefaultFaviconLinks(input: BuildFaviconLinksInput): FaviconLinkTag[] {
+export function buildFaviconLinks(input: BuildFaviconLinksInput): FaviconLinkTag[] {
   const base = resolveFaviconBase(input);
-  return DEFAULT_FAVICON_FILES.map(tag => ({
-    ...tag,
-    href: `${base}${tag.href}`,
+  const icons = input.icons && input.icons.length > 0 ? input.icons : DEFAULT_FAVICON_FILES;
+  return icons.map(icon => ({
+    rel: icon.rel,
+    type: icon.type,
+    sizes: icon.sizes,
+    href: prefixHref(icon.href, base),
   }));
 }
 
+/** Back-compat alias — older name for the same operation. */
+export const buildDefaultFaviconLinks = buildFaviconLinks;
+
+/** Decide whether to prefix the href with the base path.
+ *  Absolute URLs and root-relative paths are emitted as-is; bare filenames
+ *  and relative paths are prefixed. */
+function prefixHref(href: string, base: string): string {
+  if (!href) return base;
+  // Absolute URL: https://, http://, //, data:, etc.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//')) return href;
+  // Root-relative: /anything
+  if (href.startsWith('/')) return href;
+  // Bare filename or relative path: prefix with base.
+  return `${base}${href}`;
+}
+
 /**
  * Render a single FaviconLinkTag to an HTML <link> string.
  *