@rathnasgala2/template 2.1.0 → 3.0.0

package/src/core/index.js

@@ -100,14 +100,22 @@ import {
 } from './internal/page-kinds.js';
 import { assertProvenance } from './internal/provenance.js';
 import {
+  deriveAuthorSlugs,
+  routeSegmentForLabel,
+} from './internal/route-labels.js';
+import {
+  derivePublicBasePath,
   errorDocumentPath,
+  joinPublicRoute,
   joinBasePathAndRoute,
   projectFixedAssetPath,
   projectRouteToFilePath,
   renderRedirectDocument,
 } from './internal/route.js';
 import { buildSearchIndex } from './internal/search-index.js';
-import { resolveSocialImageUrl, twitterCardType } from './internal/seo.js';
+import { resolveSocialImage, twitterCardType } from './internal/seo.js';
+import { buildLlmsDocuments } from './internal/llms.js';
+import { buildRobotsTxt, readAiCrawlerPolicy } from './internal/robots.js';
 import { buildSitemap } from './internal/sitemap.js';
 import {
   defaultThemeStylesheetLinksHtml,
@@ -115,12 +123,12 @@ import {
 } from './internal/theme-assets.js';
 import { resolveTextDirection } from './internal/text-direction.js';
 import {
-  renderFooter,
-  renderFooterNavigation,
-  renderHeader,
+  escapeHtml,
   renderPageBody,
   renderPrimaryNavigation,
 } from './internal/skeleton.js';
+import { renderFooter, renderHeader } from './internal/chrome.js';
+import { createComponents, createMediaImage } from './internal/components.js';
 import {
   collectIncludedSources,
   compareUtf8Bytes,
@@ -133,6 +141,13 @@ const SITEMAP_ROUTE = '/sitemap.xml';
 /** @type {string} the un-joined route the static search index is published
  * at. */
 const SEARCH_INDEX_ROUTE = '/search-index.json';
+/** @type {string} the output-root path of `robots.txt` (never `basePath`-
+ * joined: only a host-root robots file is honoured by crawlers). */
+const ROBOTS_PATH = 'robots.txt';
+/** @type {string} the un-joined route of the llmstxt.org index. */
+const LLMS_ROUTE = '/llms.txt';
+/** @type {string} the un-joined route of the full-text companion. */
+const LLMS_FULL_ROUTE = '/llms-full.txt';
 
 /** @type {string} */
 const BUILD_INPUT_SCHEMA_ID = 'urn:gala:schema:build-input:2.0.0';
@@ -322,63 +337,144 @@ 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,
   });
-  const headerHtml = renderHeader({
-    homeRoute,
-    publicationName: validatedInput.publication.title,
-    logo: undefined,
-    appearanceControlHtml,
+
+  // Run before page assembly, not after: resolving each page's own images
+  // (`og:image`, hero, avatar, brand mark) needs the media pipeline's own
+  // finished `assets` list (only it knows which derivative file extension a
+  // given source image's `sourceDigest` produced — see `internal/seo.js`).
+  // This only moves the in-memory computation earlier; `mediaFiles`' actual
+  // bytes are still written to `outputDirectory` only after the route
+  // listing below, so `outputDirectory/assets/media/` still can never be
+  // mistaken for an Eleventy-rendered HTML route.
+  const {
+    assets: mediaAssets,
+    files: mediaFiles,
+    dimensions: mediaDimensions,
+  } = await processMedia(validatedInput, {
+    sourceDirectory: path.resolve(options.sourceDirectory),
   });
-  const footerNavHtml = renderFooterNavigation({
-    items: validatedInput.navigation.footerItems,
-    messages: siteMessages,
+  const mediaImage = createMediaImage({
+    mediaAssets,
+    publicBasePath,
+    mediaDimensions,
   });
-  const footerCard = validatedInput.publication.footerCard;
+  const brandMark = mediaImage(validatedInput.appearance.brandMark);
+  const searchIndexHref = joinBasePathAndRoute(
+    publicBasePath,
+    SEARCH_INDEX_ROUTE,
+  );
+  const rssHref = joinBasePathAndRoute(publicBasePath, RSS_FEED_ROUTE);
+  const publication = validatedInput.publication;
+  const footerCard = publication.footerCard;
   // Already verified render-policy-conformant HTML by
   // assertRenderPolicyCompliance's assertPolicyConformantHtml call above —
   // inserted as-is, never re-parsed as Markdown.
   const footerProfileHtml = footerCard?.enabled ? footerCard.body.body : '';
+  const authorsById = new Map(
+    validatedInput.authors.map((author) => [author.id, author]),
+  );
+  const footerAuthor =
+    authorsById.get(publication.contactAuthorId ?? '') ??
+    validatedInput.authors[0];
+  const authorSlugs = deriveAuthorSlugs(validatedInput.authors);
+  const authorHref = (
+    /** @type {import('../../types/index.d.ts').AuthorNormalized} */ author,
+  ) =>
+    joinPublicRoute(
+      publicBasePath,
+      `/authors/${authorSlugs.get(author.id) ?? author.id}`,
+    );
+  const footerComponents = createComponents({
+    messages: siteMessages,
+    site: (route) => joinPublicRoute(publicBasePath, route),
+    mediaImage,
+    authorHref,
+    authorsById,
+    recordHref: (record) =>
+      joinPublicRoute(publicBasePath, contentRoute(record.frontmatter)),
+    tagHref: (tag) =>
+      joinPublicRoute(publicBasePath, `/tags/${routeSegmentForLabel(tag)}`),
+  });
+  const footerAuthorHtml = footerAuthor
+    ? `<p class="g-label">${footerComponents.text('writtenByLabel')}</p>` +
+      `<div class="g-byline">${footerComponents.avatar(footerAuthor)}<div class="g-byline-text">` +
+      `<a href="${escapeHtml(authorHref(footerAuthor))}">${escapeHtml(footerAuthor.displayName)}</a>` +
+      `</div></div>`
+    : '';
+  const latestYear = validatedInput.content
+    .map((record) => record.frontmatter.publishedAt.slice(0, 4))
+    .sort()
+    .at(-1);
   const footerHtml = renderFooter({
-    publicationName: validatedInput.publication.title,
-    footerNavHtml,
+    homeRoute,
+    publicationName: publication.title,
+    description: publication.description,
+    brandMark,
+    socialLinks: publication.socialLinks,
+    rssHref,
+    primaryItems: validatedInput.navigation.items,
+    footerItems: validatedInput.navigation.footerItems,
+    urlPrefix,
+    authorHtml: footerAuthorHtml,
     footerProfileHtml,
-    copyrightText: undefined,
+    copyrightText: `${siteMessages.footerCopyrightPrefix} ${latestYear ? `${latestYear} ` : ''}${publication.title}`,
     messages: siteMessages,
   });
 
-  // Run before page assembly, not after: resolving each page's own
-  // `og:image`/`twitter:image` needs the media pipeline's own finished
-  // `assets` list (only it knows which derivative file extension a given
-  // source image's `sourceDigest` produced — see `internal/seo.js`). This
-  // only moves the in-memory computation earlier; `mediaFiles`' actual
-  // bytes are still written to `outputDirectory` only after the route
-  // listing below, so `outputDirectory/assets/media/` still can never be
-  // mistaken for an Eleventy-rendered HTML route.
-  const { assets: mediaAssets, files: mediaFiles } = await processMedia(
-    validatedInput,
-    { sourceDirectory: path.resolve(options.sourceDirectory) },
-  );
+  /**
+   * One page's `<header>`, with the primary navigation marking that page's
+   * own route current.
+   *
+   * @param {string | undefined} currentRoute the page's joined route
+   * @returns {string}
+   */
+  const headerFor = (currentRoute) =>
+    renderHeader({
+      homeRoute,
+      publicationName: publication.title,
+      tagline: publication.description,
+      brandMark,
+      navHtml: renderPrimaryNavigation({
+        items: validatedInput.navigation.items,
+        currentRoute,
+        messages: siteMessages,
+        urlPrefix,
+      }),
+      navItems: validatedInput.navigation.items,
+      currentRoute,
+      urlPrefix,
+      searchIndexHref,
+      appearanceControlHtml,
+      messages: siteMessages,
+    });
 
   // The site-wide feeds, resolved once so every page's feed-discovery
   // `<link>` tags and the feed documents themselves agree on the exact same
   // 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,58 +485,69 @@ 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);
+  const generatedPages = buildGeneratedPages(validatedInput, {
+    mediaAssets,
+    mediaDimensions,
+  });
   generatedPages.forEach((page, index) => {
     const joinedRoute = joinBasePathAndRoute(
       validatedInput.basePath,
       page.route,
     );
-    const navHtml = renderPrimaryNavigation({
-      items: validatedInput.navigation.items,
-      currentRoute: joinedRoute,
-      messages: siteMessages,
-    });
     const bodyHtml = renderPageBody({
       messages: siteMessages,
-      headerHtml,
-      navHtml,
+      headerHtml: headerFor(joinedRoute),
       footerHtml,
-      breadcrumbHtml: page.breadcrumbHtml,
       mainHtml: page.bodyHtml,
     });
-    const ogImage = resolveSocialImageUrl({
+    const ogImageInfo = resolveSocialImage({
       mediaAssets,
+      mediaDimensions,
       reference: page.socialImageRef,
       baseUrl: validatedInput.baseUrl,
-      basePath: validatedInput.basePath,
+      basePath: publicBasePath,
     });
+    const ogImage = ogImageInfo?.url;
     contentPages.push({
       virtualPath: `pages/${page.kind}-${index}.html`,
       content: bodyHtml,
       permalink: projectRouteToFilePath(joinedRoute, routeProfile),
       layout: 'skeleton.njk',
       data: {
-        title: page.title,
+        title: page.documentTitle ?? page.title,
+        ogTitle: page.title,
         lang: page.language,
         dir: page.direction,
         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,
+        ogImageWidth: ogImageInfo?.width,
+        ogImageHeight: ogImageInfo?.height,
+        ogImageAlt: ogImage ? page.socialImageAlt : undefined,
+        articlePublished: page.articleMeta?.publishedTime,
+        articleModified: page.articleMeta?.modifiedTime,
+        articleAuthors: page.articleMeta?.authorUrls ?? [],
+        articleTags: page.articleMeta?.tags ?? [],
+        jsonLd: page.jsonLd,
         twitterCard: twitterCardType(Boolean(ogImage)),
         atomFeedUrl: feeds.atomSelfUrl,
         rssFeedUrl: feeds.rssSelfUrl,
@@ -464,6 +571,10 @@ export async function renderPublication(buildInput, options) {
       redirectProjections.push({
         joinedSource,
         joinedTarget: joined,
+        publicTarget: joinPublicRoute(
+          publicBasePath,
+          contentRoute(record.frontmatter),
+        ),
         filePath: projectRouteToFilePath(joinedSource, routeProfile),
       });
     }
@@ -471,7 +582,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,
   }));
 
@@ -485,15 +596,9 @@ export async function renderPublication(buildInput, options) {
   // page kind's own pure body function. Pushed after the guard above so the
   // guard's own "is there anything authored to render" check is unaffected
   // by this always-present synthetic page.
-  const errorNavHtml = renderPrimaryNavigation({
-    items: validatedInput.navigation.items,
-    currentRoute: undefined,
-    messages: siteMessages,
-  });
   const errorBodyHtml = renderPageBody({
     messages: siteMessages,
-    headerHtml,
-    navHtml: errorNavHtml,
+    headerHtml: headerFor(undefined),
     footerHtml,
     mainHtml: renderErrorPageBody({ messages: siteMessages, homeRoute }),
   });
@@ -504,7 +609,8 @@ export async function renderPublication(buildInput, options) {
     permalink: errorFilePath,
     layout: 'skeleton.njk',
     data: {
-      title: /** @type {string} */ (siteMessages.errorPageHeading),
+      title: `${/** @type {string} */ (siteMessages.errorPageHeading)} | ${siteName}`,
+      ogTitle: /** @type {string} */ (siteMessages.errorPageHeading),
       lang: validatedInput.publication.defaultLanguage,
       dir: resolveTextDirection(validatedInput.publication.defaultLanguage),
       pageKind: 'error',
@@ -546,11 +652,42 @@ export async function renderPublication(buildInput, options) {
   );
   const sitemapXml = buildSitemap({
     generatedPages,
-    basePath: validatedInput.basePath,
+    basePath: publicBasePath,
     baseUrl: validatedInput.baseUrl,
   });
   const searchIndexJson = buildSearchIndex(validatedInput);
+  const absoluteSiteUrl = (/** @type {string} */ route) =>
+    new URL(
+      joinPublicRoute(publicBasePath, route),
+      validatedInput.baseUrl,
+    ).toString();
+  const robotsTxt = buildRobotsTxt({
+    aiPolicy: readAiCrawlerPolicy(validatedInput.publication),
+    sitemapUrl: absoluteSiteUrl(SITEMAP_ROUTE),
+  });
+  const llmsFilePath = projectFixedAssetPath(
+    validatedInput.basePath,
+    LLMS_ROUTE,
+  );
+  const llmsFullFilePath = projectFixedAssetPath(
+    validatedInput.basePath,
+    LLMS_FULL_ROUTE,
+  );
+  const { llmsTxt, llmsFullTxt } = buildLlmsDocuments(validatedInput, {
+    rss: feeds.rssSelfUrl,
+    atom: feeds.atomSelfUrl,
+    sitemap: absoluteSiteUrl(SITEMAP_ROUTE),
+    searchIndex: absoluteSiteUrl(SEARCH_INDEX_ROUTE),
+    full: absoluteSiteUrl(LLMS_FULL_ROUTE),
+  });
   const assetPages = [
+    { virtualPath: 'robots.html', content: robotsTxt, permalink: ROBOTS_PATH },
+    { virtualPath: 'llms.html', content: llmsTxt, permalink: llmsFilePath },
+    {
+      virtualPath: 'llms-full.html',
+      content: llmsFullTxt,
+      permalink: llmsFullFilePath,
+    },
     {
       virtualPath: 'feeds/atom.html',
       content: feeds.atomXml,
@@ -604,6 +741,18 @@ export async function renderPublication(buildInput, options) {
       searchIndexFilePath,
       { routeClass: 'asset', mediaType: 'application/json; charset=utf-8' },
     ],
+    [
+      ROBOTS_PATH,
+      { routeClass: 'asset', mediaType: 'text/plain; charset=utf-8' },
+    ],
+    [
+      llmsFilePath,
+      { routeClass: 'asset', mediaType: 'text/plain; charset=utf-8' },
+    ],
+    [
+      llmsFullFilePath,
+      { routeClass: 'asset', mediaType: 'text/plain; charset=utf-8' },
+    ],
   ]);
 
   const outputFilePaths = await listFilesSortedByUtf8Bytes(outputDirectory);