@rathnasgala2/template 2.1.0 → 2.2.0

package/README.md

@@ -354,6 +354,13 @@ allowlist: raster formats are admitted directly, and SVG is admitted only after
 in scope and expected** (TPL-H6 decision): this sanitizer is what makes a
 theme-declared SVG icon mark safe to publish.
 
+- **`baseUrl` path prefix (2.2.0).** `buildInput.baseUrl` may carry a path (a
+  GitHub project site, `https://owner.github.io/g9/`); it is not origin-only.
+  `internal/route.js#derivePublicBasePath(baseUrl, basePath)` joins that path
+  with `basePath` into the one public base path every emitted URL uses (route
+  and asset hrefs, the appearance script, stylesheet links, canonical/`og:url`,
+  feed, sitemap and search-index URLs). Output file paths still use `basePath`
+  alone, because the artifact is deployed at the hosting site root.
 - **basePath fix (LOCAL-7 follow-up; independent-review finding B2).** Before
   theme integration existed, the appearance bootstrap script's `<script src>`
   and the social-image `og:image`/`twitter:image` URL were both root-absolute,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala2/template",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Deterministic Eleventy-backed static publication renderer for Galascribe portable repositories.",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,7 +65,7 @@
     "workflows:check": "node scripts/check-workflow-pins.mjs",
     "workflows:drift": "node scripts/check-workflow-drift.mjs",
     "schema-pin:check": "node scripts/check-no-local-schema-pin.mjs",
-    "audit": "npm audit --audit-level=high",
+    "audit": "node scripts/npm-audit.mjs",
     "verify": "npm run format:check && npm run lint && npm run typecheck && npm run architecture && npm run duplication && npm run contracts:check && npm run schema-pin:check && npm test && npm run licenses:check && npm run sbom:check && npm run workflows:check && npm run audit"
   },
   "dependencies": {

package/src/core/index.js

@@ -100,7 +100,9 @@ import {
 } from './internal/page-kinds.js';
 import { assertProvenance } from './internal/provenance.js';
 import {
+  derivePublicBasePath,
   errorDocumentPath,
+  joinPublicRoute,
   joinBasePathAndRoute,
   projectFixedAssetPath,
   projectRouteToFilePath,
@@ -322,7 +324,14 @@ export async function renderPublication(buildInput, options) {
   // that navigation/footer text does not flip language from page to page
   // (see `internal/messages.js`).
   const siteMessages = getMessages(validatedInput.publication.defaultLanguage);
-  const homeRoute = joinBasePathAndRoute(validatedInput.basePath, '/');
+  // Every emitted URL carries the `baseUrl` path (for example `/g9/` on a
+  // GitHub project site); output file paths keep using `basePath` alone.
+  const publicBasePath = derivePublicBasePath(
+    validatedInput.baseUrl,
+    validatedInput.basePath,
+  );
+  const urlPrefix = derivePublicBasePath(validatedInput.baseUrl, '/');
+  const homeRoute = joinPublicRoute(publicBasePath, '/');
 
   const appearanceControlHtml = renderAppearanceControl({
     messages: siteMessages,
@@ -336,6 +345,7 @@ export async function renderPublication(buildInput, options) {
   const footerNavHtml = renderFooterNavigation({
     items: validatedInput.navigation.footerItems,
     messages: siteMessages,
+    urlPrefix,
   });
   const footerCard = validatedInput.publication.footerCard;
   // Already verified render-policy-conformant HTML by
@@ -368,17 +378,16 @@ export async function renderPublication(buildInput, options) {
   // self URLs.
   const feeds = buildFeeds(validatedInput);
   const siteName = validatedInput.publication.title;
-  const appearanceScriptHrefValue = appearanceBootstrapScriptHref(
-    validatedInput.basePath,
-  );
+  const appearanceScriptHrefValue =
+    appearanceBootstrapScriptHref(publicBasePath);
   // TPL-H3/TPL-M7: the template-owned gala-base stylesheet's own basePath-
   // joined href, computed the same way as the appearance script href above
   // so it can never drift from the physical file/manifest path written
   // below.
-  const baseStylesheetHrefValue = `/${projectFixedAssetPath(
-    validatedInput.basePath,
+  const baseStylesheetHrefValue = joinBasePathAndRoute(
+    publicBasePath,
     `/${GALA_BASE_STYLESHEET_PATH}`,
-  )}`;
+  );
 
   // The selected theme package's copied stylesheets/passive assets and the
   // ordered `<link>` markup every generated page's `<head>` inserts.
@@ -389,15 +398,16 @@ export async function renderPublication(buildInput, options) {
     ? await loadThemeAssets({
         themeDirectory: path.resolve(options.themeDirectory),
         basePath: validatedInput.basePath,
+        publicBasePath,
       })
     : undefined;
   const themeStylesheetLinksHtml = themeAssetsResult
     ? themeAssetsResult.linkTagsHtml
-    : defaultThemeStylesheetLinksHtml(validatedInput.basePath);
+    : defaultThemeStylesheetLinksHtml(publicBasePath);
 
   /** @type {{virtualPath: string, content: string, permalink: string, layout?: string, data?: Record<string, unknown>}[]} */
   const contentPages = [];
-  /** @type {{joinedSource: string, joinedTarget: string, filePath: string}[]} */
+  /** @type {{joinedSource: string, joinedTarget: string, publicTarget: string, filePath: string}[]} */
   const redirectProjections = [];
 
   const generatedPages = buildGeneratedPages(validatedInput);
@@ -410,6 +420,7 @@ export async function renderPublication(buildInput, options) {
       items: validatedInput.navigation.items,
       currentRoute: joinedRoute,
       messages: siteMessages,
+      urlPrefix,
     });
     const bodyHtml = renderPageBody({
       messages: siteMessages,
@@ -423,7 +434,7 @@ export async function renderPublication(buildInput, options) {
       mediaAssets,
       reference: page.socialImageRef,
       baseUrl: validatedInput.baseUrl,
-      basePath: validatedInput.basePath,
+      basePath: publicBasePath,
     });
     contentPages.push({
       virtualPath: `pages/${page.kind}-${index}.html`,
@@ -437,7 +448,10 @@ export async function renderPublication(buildInput, options) {
         pageKind: page.kind,
         description: page.description,
         robotsContent: page.robotsContent,
-        canonicalUrl: new URL(joinedRoute, validatedInput.baseUrl).toString(),
+        canonicalUrl: new URL(
+          joinPublicRoute(publicBasePath, page.route),
+          validatedInput.baseUrl,
+        ).toString(),
         siteName,
         ogType: page.ogType ?? 'website',
         ogImage,
@@ -464,6 +478,10 @@ export async function renderPublication(buildInput, options) {
       redirectProjections.push({
         joinedSource,
         joinedTarget: joined,
+        publicTarget: joinPublicRoute(
+          publicBasePath,
+          contentRoute(record.frontmatter),
+        ),
         filePath: projectRouteToFilePath(joinedSource, routeProfile),
       });
     }
@@ -471,7 +489,7 @@ export async function renderPublication(buildInput, options) {
 
   const redirectPages = redirectProjections.map((projection, index) => ({
     virtualPath: `redirects/${index}.html`,
-    content: renderRedirectDocument(projection.joinedTarget),
+    content: renderRedirectDocument(projection.publicTarget),
     permalink: projection.filePath,
   }));
 
@@ -489,6 +507,7 @@ export async function renderPublication(buildInput, options) {
     items: validatedInput.navigation.items,
     currentRoute: undefined,
     messages: siteMessages,
+    urlPrefix,
   });
   const errorBodyHtml = renderPageBody({
     messages: siteMessages,
@@ -546,7 +565,7 @@ export async function renderPublication(buildInput, options) {
   );
   const sitemapXml = buildSitemap({
     generatedPages,
-    basePath: validatedInput.basePath,
+    basePath: publicBasePath,
     baseUrl: validatedInput.baseUrl,
   });
   const searchIndexJson = buildSearchIndex(validatedInput);

package/src/core/internal/feeds.js

@@ -19,7 +19,7 @@
  */
 
 import { escapeHtml } from './skeleton.js';
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 import {
   contentLastModified,
   contentRoute,
@@ -66,7 +66,10 @@ export function buildFeeds(validatedInput) {
    * @returns {string} the absolute `https://` URL
    */
   const absoluteUrl = (route) =>
-    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+    new URL(
+      joinPublicRoute(derivePublicBasePath(baseUrl, basePath), route),
+      baseUrl,
+    ).toString();
 
   const siteUrl = absoluteUrl('/');
   const atomSelfUrl = absoluteUrl(ATOM_FEED_ROUTE);

package/src/core/internal/page-kinds.js

@@ -61,7 +61,7 @@ import {
 import { getMessages } from './messages.js';
 import { resolveTextDirection } from './text-direction.js';
 import { routeSegmentForLabel } from './route-labels.js';
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 
 /** Listing page size (index and per-year archive pages). Scoped decision:
  * this renderer has no externally fixed page size; 10 is a deterministic,
@@ -264,7 +264,8 @@ function latestContentTimestamp(records) {
  *   order
  */
 export function buildGeneratedPages(validatedInput) {
-  const { publication, authors, content, basePath } = validatedInput;
+  const { publication, authors, content, basePath, baseUrl } = validatedInput;
+  const publicBasePath = derivePublicBasePath(baseUrl, basePath);
   const messages = getMessages(publication.defaultLanguage);
   const authorsById = new Map(authors.map((author) => [author.id, author]));
 
@@ -272,7 +273,7 @@ export function buildGeneratedPages(validatedInput) {
    * @param {string} route an un-joined route
    * @returns {string} the `basePath`-joined absolute route
    */
-  const site = (route) => joinBasePathAndRoute(basePath, route);
+  const site = (route) => joinPublicRoute(publicBasePath, route);
 
   /**
    * @param {import('../../../types/index.d.ts').ContentBuildRecord} record

package/src/core/internal/route.js

@@ -33,6 +33,48 @@ export function joinBasePathAndRoute(basePath, route) {
   return `/${segments.join('/')}`;
 }
 
+/**
+ * Derive the public base path every emitted URL must carry from the build
+ * input: the path component of `baseUrl` (for example `/g9/` for a GitHub
+ * project site published at `https://owner.github.io/g9/`) joined with the
+ * build input's own `basePath`. Only emitted URLs (hrefs, `src`, canonical,
+ * feed, sitemap and search-index URLs) use this value; candidate-directory
+ * output file paths keep using `basePath` alone, because the artifact is
+ * deployed at the root of the hosting site.
+ *
+ * @param {string} baseUrl the build input's validated `baseUrl`
+ * @param {string} basePath the build input's `basePath`
+ * @returns {string} the public base path with a leading slash and no double
+ *   slashes. When `baseUrl` carries a path it also has a trailing slash
+ *   (`/g9/`); with an origin-only `baseUrl` the result is exactly
+ *   `basePath`'s legacy joined form (`/` or `/blog`), so origin-only output
+ *   is byte-identical to earlier releases.
+ */
+export function derivePublicBasePath(baseUrl, basePath) {
+  const urlPath = new URL(baseUrl).pathname;
+  const joined = joinBasePathAndRoute(
+    joinBasePathAndRoute(urlPath, basePath),
+    '/',
+  );
+  return joined !== '/' && urlPath !== '/' ? `${joined}/` : joined;
+}
+
+/**
+ * Join a public base path (see {@link derivePublicBasePath}) and a route
+ * into one emitted URL path. The site root route is the public base path
+ * itself (`/site/` when `baseUrl` carries a path); every other route is
+ * joined exactly like {@link joinBasePathAndRoute}.
+ *
+ * @param {string} publicBasePath the public base path
+ * @param {string} route a `canonicalRoute`
+ * @returns {string} the emitted absolute URL path
+ */
+export function joinPublicRoute(publicBasePath, route) {
+  return route === '/'
+    ? publicBasePath
+    : joinBasePathAndRoute(publicBasePath, route);
+}
+
 /**
  * Project one already-joined absolute route to its candidate-directory-
  * relative output file path.

package/src/core/internal/search-index.js

@@ -32,7 +32,7 @@
  * full-text search.
  */
 
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 import { compareUtf8Bytes } from './source-inventory.js';
 import { contentLastModified, contentRoute } from './page-kinds.js';
 
@@ -77,7 +77,10 @@ export function buildSearchIndex(validatedInput) {
    * @returns {string} the absolute `https://` URL
    */
   const absoluteUrl = (route) =>
-    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+    new URL(
+      joinPublicRoute(derivePublicBasePath(baseUrl, basePath), route),
+      baseUrl,
+    ).toString();
 
   const documents = content
     .filter(

package/src/core/internal/seo.js

@@ -78,8 +78,10 @@ export function resolveOriginalDerivativePath(mediaAssets, reference) {
  *   the media pipeline's own finished `assets` list
  * @param {{path: string, sourceDigest: string} | undefined} options.reference
  *   the candidate `resolvedFile` reference
- * @param {string} options.baseUrl the build input's origin-only `baseUrl`
- * @param {string} options.basePath the build input's `basePath` (the
+ * @param {string} options.baseUrl the build input's `baseUrl`
+ * @param {string} options.basePath the public base path
+ *   (`route.js#derivePublicBasePath`, the `baseUrl` path joined with the
+ *   build input's `basePath`; the
  *   derivative path is joined with this before being resolved against
  *   `baseUrl`, so a non-root publication's social-image URL is correct)
  * @returns {string | undefined} the absolute derivative image URL, or

package/src/core/internal/sitemap.js

@@ -18,7 +18,7 @@
  */
 
 import { escapeHtml } from './skeleton.js';
-import { joinBasePathAndRoute } from './route.js';
+import { joinPublicRoute } from './route.js';
 import { compareUtf8Bytes } from './source-inventory.js';
 
 /**
@@ -37,8 +37,9 @@ function isNoindex(page) {
  * @param {object} options build options
  * @param {readonly import('./page-kinds.js').GeneratedPage[]} options.generatedPages
  *   every page `internal/page-kinds.js` produced
- * @param {string} options.basePath the build input's `basePath`
- * @param {string} options.baseUrl the build input's origin-only `baseUrl`
+ * @param {string} options.basePath the public base path
+ *   (`route.js#derivePublicBasePath`)
+ * @param {string} options.baseUrl the build input's `baseUrl`
  * @returns {string} the exact UTF-8 `sitemap.xml` text
  */
 export function buildSitemap({ generatedPages, basePath, baseUrl }) {
@@ -47,7 +48,7 @@ export function buildSitemap({ generatedPages, basePath, baseUrl }) {
    * @returns {string} the absolute `https://` URL
    */
   const absoluteUrl = (route) =>
-    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+    new URL(joinPublicRoute(basePath, route), baseUrl).toString();
 
   const entries = generatedPages
     .filter((page) => !isNoindex(page))

package/src/core/internal/skeleton.js

@@ -88,6 +88,8 @@ const HTML_ESCAPES = Object.freeze({
   "'": ''',
 });
 
+import { joinPublicRoute } from './route.js';
+
 /**
  * Escape a string for safe insertion into HTML text or a quoted attribute
  * value.
@@ -142,19 +144,25 @@ export function renderSkipLink(messages) {
  *   `navigationItem` (or `navigationLeaf`, which never has children)
  * @param {string | undefined} currentRoute the current page's own joined
  *   route, so the matching link can carry `aria-current="page"`
+ * @param {string} urlPrefix the `baseUrl` path prefix prepended to an
+ *   internal route's href (`/` when `baseUrl` has no path)
  * @returns {string} the rendered `<li>`
  */
-function renderNavItem(item, currentRoute) {
+function renderNavItem(item, currentRoute, urlPrefix) {
   const label = escapeHtml(item.label);
   const href = escapeHtml(
-    /** @type {string} */ (item.type === 'internal' ? item.route : item.url),
+    /** @type {string} */ (
+      item.type === 'internal'
+        ? joinPublicRoute(urlPrefix, /** @type {string} */ (item.route))
+        : item.url
+    ),
   );
   const isCurrent = item.type === 'internal' && item.route === currentRoute;
   const currentAttribute = isCurrent ? ' aria-current="page"' : '';
   const children = item.children ?? [];
   const childList =
     children.length > 0
-      ? `<ul>${children.map((child) => renderNavItem(child, currentRoute)).join('')}</ul>`
+      ? `<ul>${children.map((child) => renderNavItem(child, currentRoute, urlPrefix)).join('')}</ul>`
       : '';
   return `<li><a href="${href}"${currentAttribute}>${label}</a>${childList}</li>`;
 }
@@ -170,6 +178,8 @@ function renderNavItem(item, currentRoute) {
  *   route
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
+ * @param {string} [options.urlPrefix] the `baseUrl` path prefix for internal
+ *   hrefs (default `/`)
  * @returns {string} the rendered primary navigation `<nav>`, always present
  *   even when `items` is empty (TPL-M3): every page kind renders exactly
  *   one primary-navigation landmark unconditionally
@@ -178,12 +188,17 @@ function renderNavItem(item, currentRoute) {
  *   on every page regardless of whether that publication has authored any
  *   navigation items yet.
  */
-export function renderPrimaryNavigation({ items, currentRoute, messages }) {
+export function renderPrimaryNavigation({
+  items,
+  currentRoute,
+  messages,
+  urlPrefix = '/',
+}) {
   const label = escapeHtml(
     /** @type {string} */ (messages.primaryNavigationLabel),
   );
   const itemsHtml = items
-    .map((item) => renderNavItem(item, currentRoute))
+    .map((item) => renderNavItem(item, currentRoute, urlPrefix))
     .join('');
   return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }
@@ -196,14 +211,15 @@ export function renderPrimaryNavigation({ items, currentRoute, messages }) {
  *   `navigationNormalized.footerItems` (0..50 root items)
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
+ * @param {string} [options.urlPrefix] the `baseUrl` path prefix (default `/`)
  * @returns {string} the rendered footer navigation
  */
-export function renderFooterNavigation({ items, messages }) {
+export function renderFooterNavigation({ items, messages, urlPrefix = '/' }) {
   const label = escapeHtml(
     /** @type {string} */ (messages.footerNavigationLabel),
   );
   const itemsHtml = items
-    .map((item) => renderNavItem(item, undefined))
+    .map((item) => renderNavItem(item, undefined, urlPrefix))
     .join('');
   return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }

package/src/core/internal/theme-assets.js

@@ -277,6 +277,19 @@ function joinedThemeOutputPath(basePath, themeRelativePath) {
   );
 }
 
+/**
+ * The public `<link href>` for one theme file: the same joined path as
+ * {@link joinedThemeOutputPath}, but under the public base path.
+ *
+ * @param {string} publicBasePath the public base path
+ * @param {string} themeRelativePath the file's path relative to
+ *   `THEME_ASSET_DIRECTORY`
+ * @returns {string} the root-absolute href
+ */
+function themeHref(publicBasePath, themeRelativePath) {
+  return `/${joinedThemeOutputPath(publicBasePath, themeRelativePath)}`;
+}
+
 /** @type {{maximumFileBytes: number, maximumTotalBytes: number, maximumFiles: number}} */
 const FALLBACK_BUDGETS = Object.freeze({
   maximumFileBytes: DEFAULT_MAXIMUM_PASSIVE_ASSET_BYTES,
@@ -471,6 +484,8 @@ function subresourceIntegrityAttribute(bytes) {
  *   file set `theme.json.stylesheets`/`assets` and `package.json.files`
  *   name)
  * @param {string} options.basePath the build input's `basePath`
+ * @param {string} [options.publicBasePath] the base path emitted `<link href>`
+ *   values use (`route.js#derivePublicBasePath`); defaults to `basePath`
  * @returns {Promise<{
  *   files: {path: string, bytes: Buffer}[],
  *   assets: import('../../../types/index.d.ts').ManifestAssetEntry[],
@@ -478,7 +493,11 @@ function subresourceIntegrityAttribute(bytes) {
  * }>} the files to write (already `basePath`-joined), their manifest rows
  *   (same joined paths), and the ready-to-insert `<link>` markup
  */
-export async function loadThemeAssets({ themeDirectory, basePath }) {
+export async function loadThemeAssets({
+  themeDirectory,
+  basePath,
+  publicBasePath = basePath,
+}) {
   const { bytes: themeJsonBytes } = await readDeclaredThemeFile(
     themeDirectory,
     'theme.json',
@@ -533,7 +552,7 @@ export async function loadThemeAssets({ themeDirectory, basePath }) {
     // base64, computed fresh from these exact bytes.
     const integrity = subresourceIntegrityAttribute(bytes);
     linkTags.push(
-      `<link rel="stylesheet" href="${escapeHtml(`/${outputPath}`)}" integrity="${integrity}" crossorigin="anonymous"${mediaAttribute}>`,
+      `<link rel="stylesheet" href="${escapeHtml(themeHref(publicBasePath, relativePath))}" integrity="${integrity}" crossorigin="anonymous"${mediaAttribute}>`,
     );
   }