@abreen/tada 1.17.1 → 1.18.1

package/build/utils/render.ts

@@ -1,8 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import _ from 'lodash';
+import { compileTemplate } from '../lodash-template';
 import type MarkdownIt from 'markdown-it';
-import { stripHtml } from 'string-strip-html';
 import { makeLogger } from '../log';
 import { B } from '../colors';
 import createTemplateGlobals from '../template-globals';
@@ -16,8 +15,8 @@ import {
   getSupportedConfigFileNamesText,
 } from '../config-files';
 import {
-  resolveParentLinkTarget,
-  validateParentLink,
+  resolveBreadcrumbLinkTarget,
+  validateBreadcrumbs,
 } from '../validate-config-links';
 import {
   extractJavaMethodToc,
@@ -28,9 +27,11 @@ import {
 import { extensionIsMarkdown } from './file-types';
 import { createTraceHelpers } from './trace';
 import { stripHtmlComments } from './html-comments';
+import { htmlToPlainText } from './plain-text';
 import { finalizeHtmlPage } from './final-html';
 import {
   createApplyBasePath,
+  getProjectDir,
   normalizeOutputPath,
   toPosix,
   toUrlPath,
@@ -41,7 +42,7 @@ import { parseFrontMatterAndContent } from './front-matter';
 import { createMarkdown } from './markdown';
 import { generateTocHtml, generateCodeTocHtml } from '../toc-plugin';
 import {
-  parseLiterateJava,
+  extractLiterateJavaCode,
   hasMainMethod,
   deriveClassName,
   compileJavaSource,
@@ -55,7 +56,6 @@ import type {
   RenderLiterateJavaOptions,
   RenderCopiedContentOptions,
   RenderDependencyCollector,
-  TraceToolAvailability,
 } from '../types';
 
 const log = makeLogger(import.meta.url);
@@ -66,9 +66,20 @@ export { stripHtmlComments } from './html-comments';
 
 const REQUIRED_FRONT_MATTER_FIELDS = ['title'];
 
-function isWatchMode(assetFiles: string[]): boolean {
-  return assetFiles.some(f => f.includes('watch-reload-client'));
-}
+// Internal page variables and retired front matter keys. Internal values would
+// be overwritten or, for `template`, select a nonexistent template.
+const RESERVED_FRONT_MATTER_KEYS: readonly string[] = [
+  'template',
+  'titleHtml',
+  'descriptionHtml',
+  'tocHtml',
+  'tocItems',
+  'codeFilePath',
+  'downloadName',
+  'filePath',
+  'parent',
+  'parentLabel',
+];
 
 function renderInlineField(
   md: MarkdownIt,
@@ -81,7 +92,7 @@ function renderInlineField(
   }
   const html = md.renderInline(raw);
   vars[`${field}Html`] = html;
-  vars[field] = stripHtml(html).result;
+  vars[field] = htmlToPlainText(html);
 }
 
 interface TemplateParametersInput {
@@ -120,6 +131,19 @@ function resolveAuthor(
   pageVariables.author = authorEntry;
 }
 
+function rejectReservedFrontMatterKeys(
+  pageVariables: Record<string, unknown>,
+  filePath: string,
+): void {
+  const key = RESERVED_FRONT_MATTER_KEYS.find(k =>
+    Object.hasOwn(pageVariables, k),
+  );
+  if (key) {
+    const displayPath = toPosix(path.relative(getProjectDir(), filePath));
+    throw new Error(`${displayPath}: front matter key "${key}" is reserved`);
+  }
+}
+
 function validateFrontMatter(
   pageVariables: Record<string, unknown>,
   filePath: string,
@@ -166,10 +190,17 @@ function renderSiteBanner(siteVariables: SiteVariables): string {
   return createMarkdown(siteVariables).render(siteVariables.banner);
 }
 
+// `<meta charset>` is the first element in `<head>` so browsers find it within
+// the first 1024 bytes. Tags injected into the head go right after it.
+const CHARSET_META_PATTERN = /<meta charset="UTF-8"\s*\/?>/;
+
+function insertAfterCharsetMeta(html: string, tags: string): string {
+  return html.replace(CHARSET_META_PATTERN, charsetMeta => charsetMeta + tags);
+}
+
 export function injectAssetTags(
   html: string,
   assetFiles: string[],
-  distDir: string,
   siteVariables: SiteVariables,
 ): string {
   const jsAssets = assetFiles.filter(f => f.endsWith('.js'));
@@ -181,15 +212,8 @@ export function injectAssetTags(
         `<script defer src="${normalizeOutputPath('/' + asset)}"></script>`,
     )
     .join('');
-  const criticalAssets = cssAssets.filter(f => f.includes('critical.bundle.'));
-  const asyncAssets = cssAssets.filter(f => !f.includes('critical.bundle.'));
-  const criticalTags = criticalAssets
-    .map(asset => {
-      const css = fs.readFileSync(path.join(distDir, asset), 'utf-8');
-      return `<style>${css}</style>`;
-    })
-    .join('');
-  const asyncLinkTags = asyncAssets
+  // Render-blocking on purpose: pages never paint without the full stylesheet
+  const stylesheetTags = cssAssets
     .map(
       asset =>
         `<link href="${normalizeOutputPath('/' + asset)}" rel="stylesheet">`,
@@ -197,11 +221,6 @@ export function injectAssetTags(
     .join('');
 
   const fontPreloadTags = getDefaultFontPreloadFiles(siteVariables)
-    .filter(
-      preload =>
-        preload.source === 'public' ||
-        fs.existsSync(path.join(distDir, preload.filePath)),
-    )
     .map(preload => {
       const urlPath =
         preload.source === 'public'
@@ -211,31 +230,27 @@ export function injectAssetTags(
     })
     .join('');
 
-  return html
-    .replace(
-      '<head>',
-      `<head>${fontPreloadTags}${criticalTags}${asyncLinkTags}`,
-    )
-    .replace('</head>', `${scriptTags}</head>`);
+  return insertAfterCharsetMeta(
+    html,
+    `${fontPreloadTags}${stylesheetTags}`,
+  ).replace('</head>', `${scriptTags}</head>`);
 }
 
 export function injectKatexStylesheet(html: string): string {
   const tag = `<link href="/katex/katex.min.css" rel="stylesheet">`;
-  return html.replace('<head>', `<head>${tag}`);
+  return insertAfterCharsetMeta(html, tag);
 }
 
 export function preparePageTemplateHtml({
   templateHtml,
   assetFiles,
-  distDir,
   siteVariables,
 }: {
   templateHtml: string;
   assetFiles: string[];
-  distDir: string;
   siteVariables: SiteVariables;
 }): string {
-  let html = injectAssetTags(templateHtml, assetFiles, distDir, siteVariables);
+  let html = injectAssetTags(templateHtml, assetFiles, siteVariables);
   if (templateHtml.includes('class="katex"')) {
     html = injectKatexStylesheet(html);
   }
@@ -249,13 +264,14 @@ function toContentAssetPath(contentDir: string, filePath: string): string {
 export function renderPlainTextPageAsset({
   filePath,
   contentDir,
-  distDir,
   siteVariables,
   validInternalTargets,
   assetFiles,
+  isWatchMode,
   literateJavaOutputPaths,
+  generatedPageTargets,
+  codePageSourceTargets,
   dependencyCollector,
-  cachedTraceSourceDir,
   traceCache,
   traceToolAvailability,
 }: RenderPlainTextOptions): Asset[] {
@@ -264,34 +280,21 @@ export function renderPlainTextPageAsset({
   const sourceUrlPath = normalizeOutputPath(`/${subPath}.html`);
 
   log.info`Rendering page ${B`${subPath + ext}`}`;
-  const watchMode = isWatchMode(assetFiles);
-  const { content, pageVariables, tocItems, alertIds } = renderPlainTextContent(
+  const { content, pageVariables, tocItems } = renderPlainTextContent(
     filePath,
     subPath,
     sourceUrlPath,
     siteVariables,
     validInternalTargets,
-    watchMode,
-    {
-      dependencyCollector,
-      traceCache,
-      contentDir,
-      distDir,
-      cachedTraceSourceDir,
-      traceToolAvailability,
-    },
+    isWatchMode,
+    { dependencyCollector, traceCache, contentDir, traceToolAvailability },
   );
 
-  validateFrontMatter(pageVariables, filePath);
-
-  if (!pageVariables.template) {
-    pageVariables.template = 'default';
-  }
+  pageVariables.template = 'default';
 
   if (pageVariables.toc && tocItems) {
     pageVariables.tocHtml = generateTocHtml(
       tocItems as Parameters<typeof generateTocHtml>[0],
-      alertIds,
     );
   }
 
@@ -300,7 +303,7 @@ export function renderPlainTextPageAsset({
     siteVariables,
     content,
     subPath,
-    isWatchMode: watchMode,
+    isWatchMode,
     bannerHtml: renderSiteBanner(siteVariables),
   });
 
@@ -310,16 +313,13 @@ export function renderPlainTextPageAsset({
   ) as string;
   const finalized = finalizeHtmlPage({
     filePath,
-    html: preparePageTemplateHtml({
-      templateHtml,
-      assetFiles,
-      distDir,
-      siteVariables,
-    }),
+    html: preparePageTemplateHtml({ templateHtml, assetFiles, siteVariables }),
     siteVariables,
     sourceUrlPath,
     validInternalTargets,
     literateJavaOutputPaths,
+    generatedPageTargets,
+    codePageSourceTargets,
     dependencyCollector,
   });
 
@@ -335,11 +335,13 @@ export function renderPlainTextPageAsset({
 export function renderCodePageAsset({
   filePath,
   contentDir,
-  distDir,
   siteVariables,
   assetFiles,
+  isWatchMode,
   validInternalTargets,
   literateJavaOutputPaths,
+  generatedPageTargets,
+  codePageSourceTargets,
   dependencyCollector,
 }: RenderCodePageOptions): Asset[] {
   const { dir, name, ext } = path.parse(filePath);
@@ -382,23 +384,20 @@ export function renderCodePageAsset({
     siteVariables,
     content,
     subPath,
-    isWatchMode: isWatchMode(assetFiles),
+    isWatchMode,
     bannerHtml: renderSiteBanner(siteVariables),
   });
 
   const templateHtml = render('code.html', templateParameters) as string;
   const finalized = finalizeHtmlPage({
     filePath,
-    html: preparePageTemplateHtml({
-      templateHtml,
-      assetFiles,
-      distDir,
-      siteVariables,
-    }),
+    html: preparePageTemplateHtml({ templateHtml, assetFiles, siteVariables }),
     siteVariables,
     sourceUrlPath,
     validInternalTargets,
     literateJavaOutputPaths,
+    generatedPageTargets,
+    codePageSourceTargets,
     dependencyCollector,
   });
 
@@ -442,58 +441,42 @@ export function renderCopiedContentAsset({
   return [{ assetPath: relPath, content: templated }];
 }
 
-/** Parses the file, renders using template, returns HTML & params used to generate page */
-function renderPlainTextContent(
-  filePath: string,
-  subPath: string,
-  sourceUrlPath: string,
-  siteVariables: SiteVariables,
-  validInternalTargets: Set<string>,
-  isWatchMode: boolean,
-  {
-    dependencyCollector,
-    traceCache,
-    contentDir,
-    distDir,
-    cachedTraceSourceDir,
-    traceToolAvailability,
-  }: {
-    dependencyCollector?: RenderDependencyCollector;
-    traceCache?: Map<
-      string,
-      {
-        manifestUrl: string;
-        artifactId: string;
-        highlightedSources: { file: string; highlightedSource: string }[];
-        totalSteps: number;
-        sourceMtims: Record<string, number>;
-      }
-    >;
-    contentDir?: string;
-    distDir?: string;
-    cachedTraceSourceDir?: string;
-    traceToolAvailability?: TraceToolAvailability;
-  } = {},
-): {
-  content: string | null;
-  pageVariables: Record<string, unknown>;
-  tocItems: unknown[] | null;
-  alertIds: string[];
-} {
-  const applyBasePath = createApplyBasePath(siteVariables);
+interface PreparePageVariablesInput {
+  rawPageVariables: Record<string, unknown>;
+  filePath: string;
+  subPath: string;
+  sourceUrlPath: string;
+  siteVariables: SiteVariables;
+  validInternalTargets: ReadonlySet<string>;
+  isWatchMode: boolean;
+  /** Whether this renderer supports `slides: true` (Markdown pages only) */
+  allowSlides: boolean;
+  dependencyCollector?: RenderDependencyCollector;
+}
 
-  const ext = path.extname(filePath);
-  const raw = fs.readFileSync(filePath, 'utf-8');
-  const { pageVariables, content } = parseFrontMatterAndContent(raw, ext);
-  if (pageVariables.slides === true && !extensionIsMarkdown(ext)) {
+/**
+ * Turns parsed front matter into page variables. Shared by every renderer
+ * whose source has front matter, so each one applies the same rules:
+ * Lodash processing of string values, inline Markdown for the title and
+ * description, required fields, author lookup, and breadcrumb validation.
+ */
+function preparePageVariables({
+  rawPageVariables,
+  filePath,
+  subPath,
+  sourceUrlPath,
+  siteVariables,
+  validInternalTargets,
+  isWatchMode,
+  allowSlides,
+  dependencyCollector,
+}: PreparePageVariablesInput): Record<string, unknown> {
+  rejectReservedFrontMatterKeys(rawPageVariables, filePath);
+  if (rawPageVariables.slides === true && !allowSlides) {
     throw new Error(
       `${filePath}: slides mode is only supported on Markdown pages`,
     );
   }
-  const frontMatterMd = createMarkdown(siteVariables, {
-    filePath,
-    slides: pageVariables.slides === true,
-  });
 
   // Handle substitutions inside front matter using siteVariables
   const siteOnlyParams = createTemplateParameters({
@@ -503,63 +486,129 @@ function renderPlainTextContent(
     subPath,
     isWatchMode,
   });
-  const pageVariablesProcessed: Record<string, unknown> = Object.fromEntries(
-    Object.entries(pageVariables).map(([k, v]) => [
-      k,
-      typeof v === 'string' ? _.template(v)(siteOnlyParams) : v,
+  const templateString = (value: unknown): unknown =>
+    typeof value === 'string' ? compileTemplate(value)(siteOnlyParams) : value;
+  const pageVariables: Record<string, unknown> = Object.fromEntries(
+    Object.entries(rawPageVariables).map(([key, value]) => [
+      key,
+      templateString(value),
     ]),
   );
+  if (Array.isArray(pageVariables.breadcrumbs)) {
+    pageVariables.breadcrumbs = pageVariables.breadcrumbs.map(
+      (entry: unknown) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+          return entry;
+        }
+        const breadcrumb = entry as Record<string, unknown>;
+        return {
+          ...breadcrumb,
+          label: templateString(breadcrumb.label),
+          url: templateString(breadcrumb.url),
+        };
+      },
+    );
+  }
 
   // Render title and description as inline Markdown
-  renderInlineField(frontMatterMd, pageVariablesProcessed, 'title');
-  renderInlineField(frontMatterMd, pageVariablesProcessed, 'description');
+  const frontMatterMd = createMarkdown(siteVariables, {
+    filePath,
+    slides: pageVariables.slides === true,
+  });
+  renderInlineField(frontMatterMd, pageVariables, 'title');
+  renderInlineField(frontMatterMd, pageVariables, 'description');
 
-  resolveAuthor(pageVariablesProcessed, filePath, dependencyCollector);
+  validateFrontMatter(pageVariables, filePath);
+  resolveAuthor(pageVariables, filePath, dependencyCollector);
 
-  const parentError = validateParentLink(
-    pageVariablesProcessed.parent,
+  const breadcrumbs = pageVariables.breadcrumbs;
+  validateBreadcrumbs(
+    breadcrumbs,
     filePath,
     validInternalTargets,
     sourceUrlPath,
   );
-  if (parentError) {
-    throw new Error(parentError);
+  for (const entry of breadcrumbs ?? []) {
+    const resolvedTarget = resolveBreadcrumbLinkTarget(
+      entry.url,
+      sourceUrlPath,
+    );
+    if (resolvedTarget) {
+      dependencyCollector?.internalTargets?.add(resolvedTarget);
+    }
   }
-  const resolvedParentTarget = resolveParentLinkTarget(
-    pageVariablesProcessed.parent,
+
+  return pageVariables;
+}
+
+/** Parses the file, renders using template, returns HTML & params used to generate page */
+function renderPlainTextContent(
+  filePath: string,
+  subPath: string,
+  sourceUrlPath: string,
+  siteVariables: SiteVariables,
+  validInternalTargets: ReadonlySet<string>,
+  isWatchMode: boolean,
+  {
+    dependencyCollector,
+    traceCache,
+    contentDir,
+    traceToolAvailability,
+  }: Pick<
+    RenderPlainTextOptions,
+    | 'dependencyCollector'
+    | 'traceCache'
+    | 'contentDir'
+    | 'traceToolAvailability'
+  >,
+): {
+  content: string | null;
+  pageVariables: Record<string, unknown>;
+  tocItems: unknown[] | null;
+} {
+  const applyBasePath = createApplyBasePath(siteVariables);
+
+  const ext = path.extname(filePath);
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { pageVariables: rawPageVariables, content } =
+    parseFrontMatterAndContent(raw, ext);
+  const pageVariables = preparePageVariables({
+    rawPageVariables,
+    filePath,
+    subPath,
     sourceUrlPath,
-  );
-  if (resolvedParentTarget) {
-    dependencyCollector?.internalTargets?.add(resolvedParentTarget);
-  }
+    siteVariables,
+    validInternalTargets,
+    isWatchMode,
+    allowSlides: extensionIsMarkdown(ext),
+    dependencyCollector,
+  });
 
   const strippedContent = stripHtmlComments(content);
 
   const params = createTemplateParameters({
-    pageVariables: pageVariablesProcessed,
+    pageVariables,
     siteVariables,
     content: strippedContent,
     subPath,
     isWatchMode,
   });
 
-  if (traceCache && contentDir && distDir) {
+  if (traceCache) {
     const helpers = createTraceHelpers({
       filePath,
       contentDir,
-      distDir,
       applyBasePath,
       cache: traceCache,
       toolAvailability: traceToolAvailability,
       dependencyCollector,
-      cachedTraceSourceDir,
     });
     params.renderTrace = helpers.renderTrace;
   }
 
   let html: string;
   try {
-    html = _.template(strippedContent)(params);
+    html = compileTemplate(strippedContent)(params);
   } catch (err: unknown) {
     throw new Error(
       `${filePath}: Lodash template error in page or template: ${(err as Error).message}`,
@@ -568,7 +617,6 @@ function renderPlainTextContent(
   }
 
   let tocItems: unknown[] | null = null;
-  let alertIds: string[] = [];
   if (extensionIsMarkdown(ext)) {
     const md = createMarkdown(siteVariables, {
       filePath,
@@ -576,29 +624,29 @@ function renderPlainTextContent(
       templateParams: params,
       dependencyCollector,
     });
-    const env: Record<string, unknown> = { alertIds: [] as string[] };
+    const env: Record<string, unknown> = {};
     html = md.render(html!, env);
     tocItems = (env.tocItems as unknown[] | undefined) || null;
-    alertIds = env.alertIds as string[];
   }
 
   return {
     content: html,
     pageVariables: params.page as Record<string, unknown>,
     tocItems,
-    alertIds,
   };
 }
 
 export function renderLiterateJavaPageAsset({
   filePath,
   contentDir,
-  distDir,
   siteVariables,
   assetFiles,
+  isWatchMode,
   skipExecution,
   validInternalTargets,
   literateJavaOutputPaths,
+  generatedPageTargets,
+  codePageSourceTargets,
   dependencyCollector,
 }: RenderLiterateJavaOptions): Asset[] {
   const { dir, name } = path.parse(filePath);
@@ -607,16 +655,38 @@ export function renderLiterateJavaPageAsset({
 
   log.info`Rendering literate Java page ${B`${name}`}`;
 
+  const sourceUrlPath = `/${subPath}.java.html`;
   const raw = fs.readFileSync(filePath, 'utf-8');
-  const {
+  const { pageVariables: rawPageVariables, content } =
+    parseFrontMatterAndContent(raw, '.md');
+  const pageVariables = preparePageVariables({
+    rawPageVariables,
+    filePath,
+    subPath,
+    sourceUrlPath,
+    siteVariables,
+    validInternalTargets,
+    isWatchMode,
+    allowSlides: false,
+    dependencyCollector,
+  });
+  const params = createTemplateParameters({
     pageVariables,
+    siteVariables,
     content,
-    javaSource,
-    codeBlocks,
-    visibleBlockIndices,
-  } = parseLiterateJava(raw, siteVariables);
-
-  validateFrontMatter(pageVariables, filePath);
+    subPath,
+    isWatchMode,
+  });
+  const md = createMarkdown(siteVariables, {
+    filePath,
+    templateParams: params,
+    preserveHtmlComments: true,
+    dependencyCollector,
+  });
+  const env: Record<string, unknown> = {};
+  const tokens = md.parse(compileTemplate(content)(params), env);
+  const { javaSource, codeBlocks, visibleBlockIndices } =
+    extractLiterateJavaCode(tokens);
 
   const stdin =
     typeof pageVariables.stdin === 'string' ? pageVariables.stdin : undefined;
@@ -649,8 +719,6 @@ export function renderLiterateJavaPageAsset({
 
   // Render full markdown with a custom fence rule that replaces fences
   // with Shiki-highlighted code blocks and optional JDI output columns
-  const sourceUrlPath = `/${subPath}.java.html`;
-  const md = createMarkdown(siteVariables, { filePath });
   let fenceIndex = 0;
   const defaultFence = md.renderer.rules.fence!;
 
@@ -698,8 +766,9 @@ export function renderLiterateJavaPageAsset({
     return codeHtml;
   };
 
-  const env: Record<string, unknown> = { alertIds: [] as string[] };
-  const contentHtml = md.render(stripHtmlComments(content), env);
+  const contentHtml = stripHtmlComments(
+    md.renderer.render(tokens, md.options, env),
+  );
 
   // Build page variables
   const javaFileName = `${className}.java`;
@@ -707,7 +776,6 @@ export function renderLiterateJavaPageAsset({
     `/${toUrlPath(path.relative(contentDir, path.join(dir, javaFileName)))}`,
   );
 
-  renderInlineField(md, pageVariables, 'title');
   pageVariables.template = 'literate';
   pageVariables.codeFilePath = codeFilePath;
   pageVariables.downloadName = javaFileName;
@@ -715,34 +783,28 @@ export function renderLiterateJavaPageAsset({
   if (pageVariables.toc && env.tocItems) {
     pageVariables.tocHtml = generateTocHtml(
       env.tocItems as Parameters<typeof generateTocHtml>[0],
-      env.alertIds as string[],
     );
   }
 
-  resolveAuthor(pageVariables, filePath, dependencyCollector);
-
   const templateParameters = createTemplateParameters({
     pageVariables,
     siteVariables,
     content: contentHtml,
     subPath,
-    isWatchMode: isWatchMode(assetFiles),
+    isWatchMode,
     bannerHtml: renderSiteBanner(siteVariables),
   });
 
   const templateHtml = render('literate.html', templateParameters) as string;
   const finalized = finalizeHtmlPage({
     filePath,
-    html: preparePageTemplateHtml({
-      templateHtml,
-      assetFiles,
-      distDir,
-      siteVariables,
-    }),
+    html: preparePageTemplateHtml({ templateHtml, assetFiles, siteVariables }),
     siteVariables,
     sourceUrlPath,
     validInternalTargets,
     literateJavaOutputPaths,
+    generatedPageTargets,
+    codePageSourceTargets,
     dependencyCollector,
   });