@abreen/tada 1.11.2 → 1.13.2

package/build/utils/render.ts

@@ -5,10 +5,18 @@ import type MarkdownIt from 'markdown-it';
 import { stripHtml } from 'string-strip-html';
 import { makeLogger } from '../log';
 import { B } from '../colors';
-import createGlobals from '../globals';
+import createTemplateGlobals from '../template-globals';
 import { getExtensionToShikiLanguage } from '../site-variables';
-import { render, json } from '../templates';
-import { validateParentLink } from '../validate-config-links';
+import { config } from '../templates';
+import { render } from '../templates';
+import {
+  getProjectConfigBaseName,
+  getSupportedConfigFileNamesText,
+} from '../config-files';
+import {
+  resolveParentLinkTarget,
+  validateParentLink,
+} from '../validate-config-links';
 import {
   extractJavaMethodToc,
   renderCodeSegment,
@@ -18,6 +26,7 @@ import {
 import { extensionIsMarkdown } from './file-types';
 import { createTraceHelpers } from './trace';
 import { createIncludeFunction } from './include';
+import { finalizeHtmlPage } from './final-html';
 import {
   createApplyBasePath,
   normalizeOutputPath,
@@ -75,7 +84,6 @@ interface TemplateParametersInput {
   pageVariables: Record<string, unknown>;
   siteVariables: SiteVariables;
   content: string | null;
-  applyBasePath: (subPath: string) => string;
   subPath: string;
   isWatchMode: boolean;
 }
@@ -88,12 +96,12 @@ function resolveAuthor(
   if (!pageVariables.author) {
     return;
   }
-  const authors = json('authors.json') as
+  const authors = config('authors') as
     | Record<string, Record<string, unknown>>
     | undefined;
   if (!authors) {
     throw new Error(
-      `${filePath}: author "${pageVariables.author}" specified but no authors.json found`,
+      `${filePath}: author "${pageVariables.author}" specified but no author config found (tried ${getSupportedConfigFileNamesText(getProjectConfigBaseName('authors'))})`,
     );
   }
   const authorKey = pageVariables.author as string;
@@ -101,7 +109,7 @@ function resolveAuthor(
   const authorEntry = authors[authorKey];
   if (!authorEntry) {
     throw new Error(
-      `${filePath}: unknown author "${authorKey}" (not found in authors.json)`,
+      `${filePath}: unknown author "${authorKey}" (not found in author config)`,
     );
   }
   pageVariables.author = authorEntry;
@@ -127,18 +135,18 @@ function createTemplateParameters({
   pageVariables,
   siteVariables,
   content,
-  applyBasePath,
   subPath,
   isWatchMode,
 }: TemplateParametersInput): Record<string, unknown> {
+  const applyBasePath = createApplyBasePath(siteVariables);
   return {
     vars: siteVariables.vars || {},
-    ...createGlobals(pageVariables, siteVariables, subPath),
+    ...createTemplateGlobals(pageVariables, siteVariables, subPath),
     site: siteVariables,
     page: pageVariables,
     content,
-    applyBasePath,
     isWatchMode,
+    speculationRulesHrefMatches: `${applyBasePath('/')}*`,
     tadaVersion,
   };
 }
@@ -146,14 +154,16 @@ function createTemplateParameters({
 export function injectAssetTags(
   html: string,
   assetFiles: string[],
-  applyBasePath: (subPath: string) => string,
   distDir: string,
 ): string {
   const jsAssets = assetFiles.filter(f => f.endsWith('.js'));
   const cssAssets = assetFiles.filter(f => f.endsWith('.css'));
 
   const scriptTags = jsAssets
-    .map(asset => `<script defer src="${applyBasePath('/' + asset)}"></script>`)
+    .map(
+      asset =>
+        `<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.'));
@@ -165,7 +175,8 @@ export function injectAssetTags(
     .join('');
   const asyncLinkTags = asyncAssets
     .map(
-      asset => `<link href="${applyBasePath('/' + asset)}" rel="stylesheet">`,
+      asset =>
+        `<link href="${normalizeOutputPath('/' + asset)}" rel="stylesheet">`,
     )
     .join('');
 
@@ -176,7 +187,7 @@ export function injectAssetTags(
     .filter(f => fs.existsSync(path.join(distDir, f)))
     .map(
       f =>
-        `<link rel="preload" href="${applyBasePath('/' + f)}" as="font" type="font/woff2" crossorigin>`,
+        `<link rel="preload" href="${normalizeOutputPath('/' + f)}" as="font" type="font/woff2" crossorigin>`,
     )
     .join('');
 
@@ -188,15 +199,27 @@ export function injectAssetTags(
     .replace('</head>', `${scriptTags}</head>`);
 }
 
-export function injectKatexStylesheet(
-  html: string,
-  applyBasePath: (subPath: string) => string,
-): string {
-  const href = applyBasePath('/katex/katex.min.css');
-  const tag = `<link href="${href}" rel="stylesheet">`;
+export function injectKatexStylesheet(html: string): string {
+  const tag = `<link href="/katex/katex.min.css" rel="stylesheet">`;
   return html.replace('<head>', `<head>${tag}`);
 }
 
+export function preparePageTemplateHtml({
+  templateHtml,
+  assetFiles,
+  distDir,
+}: {
+  templateHtml: string;
+  assetFiles: string[];
+  distDir: string;
+}): string {
+  let html = injectAssetTags(templateHtml, assetFiles, distDir);
+  if (templateHtml.includes('class="katex"')) {
+    html = injectKatexStylesheet(html);
+  }
+  return html;
+}
+
 function toContentAssetPath(contentDir: string, filePath: string): string {
   return toPosix(path.relative(contentDir, filePath));
 }
@@ -216,24 +239,22 @@ export function renderPlainTextPageAsset({
 }: RenderPlainTextOptions): Asset[] {
   const { dir, name, ext } = path.parse(filePath);
   const subPath = toPosix(path.relative(contentDir, path.join(dir, name)));
-  const applyBasePath = createApplyBasePath(siteVariables);
+  const sourceUrlPath = normalizeOutputPath(`/${subPath}.html`);
 
   log.info`Rendering page ${B`${subPath + ext}`}`;
   const watchMode = isWatchMode(assetFiles);
   const { content, pageVariables, tocItems, alertIds } = renderPlainTextContent(
     filePath,
     subPath,
+    sourceUrlPath,
     siteVariables,
-    applyBasePath,
     validInternalTargets,
     watchMode,
     {
-      validateInternalLinks: extensionIsMarkdown(ext.toLowerCase()),
       dependencyCollector,
       traceCache,
       contentDir,
       distDir,
-      literateJavaOutputPaths,
       cachedTraceSourceDir,
       traceToolAvailability,
     },
@@ -256,7 +277,6 @@ export function renderPlainTextPageAsset({
     pageVariables,
     siteVariables,
     content,
-    applyBasePath,
     subPath,
     isWatchMode: watchMode,
   });
@@ -265,15 +285,21 @@ export function renderPlainTextPageAsset({
     `${pageVariables.template}.html`,
     templateParameters,
   ) as string;
-  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
-  if (templateHtml.includes('class="katex"')) {
-    html = injectKatexStylesheet(html, applyBasePath);
-  }
+  const finalized = finalizeHtmlPage({
+    filePath,
+    html: preparePageTemplateHtml({ templateHtml, assetFiles, distDir }),
+    siteVariables,
+    sourceUrlPath,
+    validInternalTargets,
+    literateJavaOutputPaths,
+    dependencyCollector,
+  });
 
   return [
     {
       assetPath: toContentAssetPath(contentDir, path.join(dir, `${name}.html`)),
-      content: html,
+      content: finalized.html,
+      htmlAnalysis: finalized.analysis,
     },
   ];
 }
@@ -286,10 +312,10 @@ export function renderCodePageAsset({
   assetFiles,
   validInternalTargets,
   literateJavaOutputPaths,
+  dependencyCollector,
 }: RenderCodePageOptions): Asset[] {
   const { dir, name, ext } = path.parse(filePath);
   const subPath = toPosix(path.relative(contentDir, path.join(dir, name)));
-  const applyBasePath = createApplyBasePath(siteVariables);
   const lang =
     getExtensionToShikiLanguage(siteVariables)[ext.slice(1).toLowerCase()];
   const rawSource = fs.readFileSync(filePath, 'utf-8');
@@ -305,12 +331,9 @@ export function renderCodePageAsset({
     lang,
     siteVariables,
     pageDirPath,
-    sourceUrlPath,
-    validInternalTargets,
-    literateJavaOutputPaths,
   );
-  const codeFilePath = applyBasePath(
-    normalizeOutputPath(`/${toUrlPath(path.relative(contentDir, filePath))}`),
+  const codeFilePath = normalizeOutputPath(
+    `/${toUrlPath(path.relative(contentDir, filePath))}`,
   );
   const titleHtml = `<code>${name + ext}</code>`;
   const tocItems = lang === 'java' ? extractJavaMethodToc(sourceCode) : [];
@@ -330,17 +353,23 @@ export function renderCodePageAsset({
     pageVariables,
     siteVariables,
     content,
-    applyBasePath,
     subPath,
     isWatchMode: isWatchMode(assetFiles),
   });
 
-  const html = injectAssetTags(
-    render('code.html', templateParameters) as string,
-    assetFiles,
-    applyBasePath,
-    distDir,
-  );
+  const finalized = finalizeHtmlPage({
+    filePath,
+    html: injectAssetTags(
+      render('code.html', templateParameters) as string,
+      assetFiles,
+      distDir,
+    ),
+    siteVariables,
+    sourceUrlPath,
+    validInternalTargets,
+    literateJavaOutputPaths,
+    dependencyCollector,
+  });
 
   return [
     {
@@ -348,7 +377,8 @@ export function renderCodePageAsset({
         contentDir,
         path.join(dir, `${name}${ext}.html`),
       ),
-      content: html,
+      content: finalized.html,
+      htmlAnalysis: finalized.analysis,
     },
   ];
 }
@@ -385,21 +415,18 @@ export function renderCopiedContentAsset({
 function renderPlainTextContent(
   filePath: string,
   subPath: string,
+  sourceUrlPath: string,
   siteVariables: SiteVariables,
-  applyBasePath: (subPath: string) => string,
   validInternalTargets: Set<string>,
   isWatchMode: boolean,
   {
-    validateInternalLinks = true,
     dependencyCollector,
     traceCache,
     contentDir,
     distDir,
-    literateJavaOutputPaths,
     cachedTraceSourceDir,
     traceToolAvailability,
   }: {
-    validateInternalLinks?: boolean;
     dependencyCollector?: RenderDependencyCollector;
     traceCache?: Map<
       string,
@@ -412,7 +439,6 @@ function renderPlainTextContent(
     >;
     contentDir?: string;
     distDir?: string;
-    literateJavaOutputPaths?: Set<string>;
     cachedTraceSourceDir?: string;
     traceToolAvailability?: TraceToolAvailability;
   } = {},
@@ -422,35 +448,26 @@ function renderPlainTextContent(
   tocItems: unknown[] | null;
   alertIds: string[];
 } {
-  const sourceUrlPath = `/${subPath}.html`;
-  const md = createMarkdown(siteVariables, {
-    filePath,
-    validatorOptions: {
-      enabled: validateInternalLinks,
-      filePath,
-      sourceUrlPath,
-      validTargets: validInternalTargets,
-      codeExtensions: Object.keys(getExtensionToShikiLanguage(siteVariables)),
-      onValidLink: (targetPath: string) => {
-        dependencyCollector?.internalTargets?.add(targetPath);
-      },
-    },
-    literateJavaOutputPaths,
-    sourceUrlPath,
-    validTargets: validInternalTargets,
-  });
+  const applyBasePath = createApplyBasePath(siteVariables);
 
   const ext = path.extname(filePath);
   const raw = fs.readFileSync(filePath, 'utf-8');
-
   const { pageVariables, content } = parseFrontMatterAndContent(raw, ext);
+  if (pageVariables.slides === true && !extensionIsMarkdown(ext)) {
+    throw new Error(
+      `${filePath}: slides mode is only supported on Markdown pages`,
+    );
+  }
+  const md = createMarkdown(siteVariables, {
+    filePath,
+    slides: pageVariables.slides === true,
+  });
 
   // Handle substitutions inside front matter using siteVariables
   const siteOnlyParams = createTemplateParameters({
     pageVariables: {},
     siteVariables,
     content: null,
-    applyBasePath,
     subPath,
     isWatchMode,
   });
@@ -471,14 +488,17 @@ function renderPlainTextContent(
     pageVariablesProcessed.parent,
     filePath,
     validInternalTargets,
+    sourceUrlPath,
   );
   if (parentError) {
     throw new Error(parentError);
   }
-  if (typeof pageVariablesProcessed.parent === 'string') {
-    dependencyCollector?.internalTargets?.add(
-      normalizeOutputPath(pageVariablesProcessed.parent),
-    );
+  const resolvedParentTarget = resolveParentLinkTarget(
+    pageVariablesProcessed.parent,
+    sourceUrlPath,
+  );
+  if (resolvedParentTarget) {
+    dependencyCollector?.internalTargets?.add(resolvedParentTarget);
   }
 
   const strippedContent = stripHtmlComments(content);
@@ -487,7 +507,6 @@ function renderPlainTextContent(
     pageVariables: pageVariablesProcessed,
     siteVariables,
     content: strippedContent,
-    applyBasePath,
     subPath,
     isWatchMode,
   });
@@ -553,7 +572,6 @@ export function renderLiterateJavaPageAsset({
   const { dir, name } = path.parse(filePath);
   const className = deriveClassName(filePath);
   const subPath = toPosix(path.relative(contentDir, path.join(dir, className)));
-  const applyBasePath = createApplyBasePath(siteVariables);
 
   log.info`Rendering literate Java page ${B`${name}`}`;
 
@@ -600,21 +618,7 @@ 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,
-    validatorOptions: {
-      filePath,
-      sourceUrlPath,
-      validTargets: validInternalTargets,
-      codeExtensions: Object.keys(getExtensionToShikiLanguage(siteVariables)),
-      onValidLink: (targetPath: string) => {
-        dependencyCollector?.internalTargets?.add(targetPath);
-      },
-    },
-    literateJavaOutputPaths,
-    sourceUrlPath,
-    validTargets: validInternalTargets,
-  });
+  const md = createMarkdown(siteVariables, { filePath });
   let fenceIndex = 0;
   const defaultFence = md.renderer.rules.fence!;
 
@@ -667,10 +671,8 @@ export function renderLiterateJavaPageAsset({
 
   // Build page variables
   const javaFileName = `${className}.java`;
-  const codeFilePath = applyBasePath(
-    normalizeOutputPath(
-      `/${toUrlPath(path.relative(contentDir, path.join(dir, javaFileName)))}`,
-    ),
+  const codeFilePath = normalizeOutputPath(
+    `/${toUrlPath(path.relative(contentDir, path.join(dir, javaFileName)))}`,
   );
 
   renderInlineField(md, pageVariables, 'title');
@@ -691,16 +693,20 @@ export function renderLiterateJavaPageAsset({
     pageVariables,
     siteVariables,
     content: contentHtml,
-    applyBasePath,
     subPath,
     isWatchMode: isWatchMode(assetFiles),
   });
 
   const templateHtml = render('literate.html', templateParameters) as string;
-  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
-  if (templateHtml.includes('class="katex"')) {
-    html = injectKatexStylesheet(html, applyBasePath);
-  }
+  const finalized = finalizeHtmlPage({
+    filePath,
+    html: preparePageTemplateHtml({ templateHtml, assetFiles, distDir }),
+    siteVariables,
+    sourceUrlPath,
+    validInternalTargets,
+    literateJavaOutputPaths,
+    dependencyCollector,
+  });
 
   return [
     {
@@ -708,7 +714,8 @@ export function renderLiterateJavaPageAsset({
         contentDir,
         path.join(dir, `${className}.java.html`),
       ),
-      content: html,
+      content: finalized.html,
+      htmlAnalysis: finalized.analysis,
     },
     {
       assetPath: toContentAssetPath(contentDir, path.join(dir, javaFileName)),
@@ -716,3 +723,5 @@ export function renderLiterateJavaPageAsset({
     },
   ];
 }
+
+export { finalizeHtmlPage } from './final-html';

package/build/validate-config-links.ts

@@ -1,3 +1,4 @@
+import path from 'path';
 import { normalizeOutputPath } from './utils/paths';
 
 interface NavLink {
@@ -12,9 +13,21 @@ interface NavSection {
   links: NavLink[];
 }
 
+function requireRootRelativePath(
+  value: string,
+  errorPrefix: string,
+): string | null {
+  if (value.startsWith('/')) {
+    return null;
+  }
+
+  return `${errorPrefix} must start with "/": "${value}"`;
+}
+
 export function validateNavLinks(
   navData: unknown,
   validTargets: Set<string>,
+  fileName: string = 'nav.yaml',
 ): string[] {
   if (!Array.isArray(navData)) {
     return [];
@@ -28,10 +41,19 @@ export function validateNavLinks(
         continue;
       }
 
+      const rootRelativeError = requireRootRelativePath(
+        link.internal,
+        `${fileName}: internal link in section "${section.title}"`,
+      );
+      if (rootRelativeError) {
+        errors.push(rootRelativeError);
+        continue;
+      }
+
       const normalized = normalizeOutputPath(link.internal);
       if (!validTargets.has(normalized)) {
         errors.push(
-          `nav.json: broken internal link in section "${section.title}": "${link.internal}"`,
+          `${fileName}: broken internal link in section "${section.title}": "${link.internal}"`,
         );
       }
     }
@@ -49,6 +71,7 @@ interface AuthorEntry {
 export function validateAuthorLinks(
   authorsData: unknown,
   validTargets: Set<string>,
+  fileName: string = 'authors.yaml',
 ): string[] {
   if (!authorsData || typeof authorsData !== 'object') {
     return [];
@@ -58,17 +81,33 @@ export function validateAuthorLinks(
   const authors = authorsData as Record<string, AuthorEntry>;
 
   for (const [key, author] of Object.entries(authors)) {
-    const avatarPath = normalizeOutputPath(author.avatar);
-    if (!validTargets.has(avatarPath)) {
-      errors.push(
-        `authors.json: broken avatar path for "${key}": "${author.avatar}"`,
-      );
+    const avatarRootRelativeError = requireRootRelativePath(
+      author.avatar,
+      `${fileName}: avatar path for "${key}"`,
+    );
+    if (avatarRootRelativeError) {
+      errors.push(avatarRootRelativeError);
+    } else {
+      const avatarPath = normalizeOutputPath(author.avatar);
+      if (!validTargets.has(avatarPath)) {
+        errors.push(
+          `${fileName}: broken avatar path for "${key}": "${author.avatar}"`,
+        );
+      }
     }
 
     if (author.url) {
-      const urlPath = normalizeOutputPath(author.url);
-      if (!validTargets.has(urlPath)) {
-        errors.push(`authors.json: broken url for "${key}": "${author.url}"`);
+      const urlRootRelativeError = requireRootRelativePath(
+        author.url,
+        `${fileName}: url for "${key}"`,
+      );
+      if (urlRootRelativeError) {
+        errors.push(urlRootRelativeError);
+      } else {
+        const urlPath = normalizeOutputPath(author.url);
+        if (!validTargets.has(urlPath)) {
+          errors.push(`${fileName}: broken url for "${key}": "${author.url}"`);
+        }
       }
     }
   }
@@ -80,26 +119,64 @@ export function validateConfigLinks(
   validTargets: Set<string>,
   navData: unknown,
   authorsData: unknown,
+  {
+    navFileName = 'nav.yaml',
+    authorsFileName = 'authors.yaml',
+  }: { navFileName?: string; authorsFileName?: string } = {},
 ): string[] {
   return [
-    ...validateNavLinks(navData, validTargets),
-    ...validateAuthorLinks(authorsData, validTargets),
+    ...validateNavLinks(navData, validTargets, navFileName),
+    ...validateAuthorLinks(authorsData, validTargets, authorsFileName),
   ];
 }
 
+function splitHref(href: string): { pathname: string; suffix: string } {
+  const match = href.match(/^([^?#]*)(.*)$/);
+  return { pathname: match ? match[1] : href, suffix: match ? match[2] : '' };
+}
+
 export function validateParentLink(
   parent: unknown,
   filePath: string,
   validTargets: Set<string>,
+  sourceUrlPath: string,
 ): string | null {
-  if (!parent || typeof parent !== 'string') {
+  if (typeof parent === 'string' && splitHref(parent).pathname === '') {
+    return `${filePath}: broken parent link: "${parent}"`;
+  }
+
+  const resolvedTarget = resolveParentLinkTarget(parent, sourceUrlPath);
+  if (!resolvedTarget) {
     return null;
   }
 
-  const normalized = normalizeOutputPath(parent);
-  if (!validTargets.has(normalized)) {
+  if (!validTargets.has(resolvedTarget)) {
     return `${filePath}: broken parent link: "${parent}"`;
   }
 
   return null;
 }
+
+export function resolveParentLinkTarget(
+  parent: unknown,
+  sourceUrlPath: string,
+): string | null {
+  if (!parent || typeof parent !== 'string') {
+    return null;
+  }
+
+  const { pathname } = splitHref(parent);
+  if (!pathname) {
+    return null;
+  }
+  const sourceDir = path.posix.dirname(sourceUrlPath);
+  const resolved = pathname.startsWith('/')
+    ? normalizeOutputPath(pathname)
+    : normalizeOutputPath(path.posix.join(sourceDir, pathname));
+
+  try {
+    return normalizeOutputPath(decodeURIComponent(resolved));
+  } catch {
+    return resolved;
+  }
+}

package/build/watch/assets.ts

@@ -34,7 +34,6 @@ export async function ensureHighlighter(
 export async function bundleWatchAssets(
   outputDir: string,
   siteVariables: SiteVariables,
-  wsPort: number,
 ): Promise<string[]> {
   const appAssets = await bundle(siteVariables, {
     mode: 'development',
@@ -45,7 +44,6 @@ export async function bundleWatchAssets(
     outdir: outputDir,
     naming: '[name].bundle.[ext]',
     sourcemap: 'inline',
-    define: { __WEBSOCKET_PORT__: String(wsPort) },
   });
   return [
     ...appAssets,