@abreen/tada 1.1.0 → 1.2.0

package/build/templates.ts

@@ -1,11 +1,11 @@
 import fs from 'fs';
 import path from 'path';
 import _ from 'lodash';
-import { compile as compileJsonSchema, doValidation } from './json-schema.js';
-import { makeLogger } from './log.js';
-import { getPackageDir, getConfigDir } from './utils/paths.js';
+import { compile as compileJsonSchema, doValidation } from './json-schema';
+import { makeLogger } from './log';
+import { getPackageDir, getConfigDir } from './utils/paths';
 import type { ValidateFunction } from 'ajv';
-import type { Logger, SiteVariables } from './types.js';
+import type { Logger, SiteVariables } from './types';
 
 const log: Logger = makeLogger(__filename);
 
@@ -100,9 +100,10 @@ export function compileTemplates(
       continue;
     }
 
-    // Schema validation (schemas live in the package templates dir)
+    // Schema validation
+    const schemaDir = path.resolve(getPackageDir(), 'schema');
     const schemaFile = `${path.parse(fileName).name}.schema.json`;
-    const schemaPath = path.join(htmlDir, schemaFile);
+    const schemaPath = path.join(schemaDir, schemaFile);
     if (!fs.existsSync(schemaPath)) {
       throw new Error(`Missing JSON Schema for ${fileName}: ${schemaPath}`);
     }

package/build/toc-plugin.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
-import { generateTocHtml, generateCodeTocHtml } from './toc-plugin.js';
-import type { JavaTocEntry } from './types.js';
+import { generateTocHtml, generateCodeTocHtml } from './toc-plugin';
+import type { JavaTocEntry } from './types';
 
 describe('generateTocHtml', () => {
   test('returns empty string for empty array', () => {

package/build/toc-plugin.ts

@@ -1,6 +1,6 @@
 import type MarkdownIt from 'markdown-it';
 import { convertMarkdown as curlyQuote } from 'quote-quote';
-import type { JavaTocEntry } from './types.js';
+import type { JavaTocEntry } from './types';
 
 interface HeadingItem {
   kind: 'heading';

package/build/types.ts

@@ -2,23 +2,28 @@
 export interface SiteVariables {
   base: string;
   basePath: string;
-  title?: string;
-  titlePostfix?: string;
+  title: string;
+  titlePostfix: string;
   symbol?: string;
   faviconSymbol?: string;
-  courseId?: string;
-  themeColor?: string;
+  themeColor: string;
   faviconColor?: string;
   faviconFontWeight?: number;
   internalDomains?: string[];
-  defaultTimeZone?: string;
-  features?: { search?: boolean; code?: boolean; favicon?: boolean };
+  defaultTimeZone: string;
+  features?: FeatureConfig;
   codeLanguages?: Record<string, string>;
   tintHue?: number;
   tintAmount?: number;
   vars?: Record<string, unknown>;
 }
 
+export type FeatureConfig = {
+  search: boolean;
+  code: boolean;
+  favicon: boolean;
+};
+
 /** A rendered content asset ready to write to dist/ */
 export interface Asset {
   assetPath: string;
@@ -69,6 +74,7 @@ export interface Logger {
 export interface RenderPlainTextOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   validInternalTargets: Set<string>;
   assetFiles: string[];
@@ -78,6 +84,7 @@ export interface RenderPlainTextOptions {
 export interface RenderCodePageOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
 }
@@ -86,6 +93,7 @@ export interface RenderCodePageOptions {
 export interface RenderLiterateJavaOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
   skipExecution?: boolean;
@@ -169,4 +177,5 @@ export interface SiteConfigInput {
   base: string;
   basePath: string;
   internalDomains: string[];
+  features: FeatureConfig;
 }

package/build/util.ts

@@ -4,9 +4,9 @@ export {
   getFilesByExtensions,
   getValidInternalTargets,
   shouldSkipContentFile,
-} from './utils/content-files.js';
-export { extensionIsMarkdown } from './utils/file-types.js';
-export { createMarkdown } from './utils/markdown.js';
+} from './utils/content-files';
+export { extensionIsMarkdown } from './utils/file-types';
+export { createMarkdown } from './utils/markdown';
 export {
   createApplyBasePath,
   getContentDir,
@@ -15,12 +15,12 @@ export {
   getProjectDir,
   getPublicDir,
   normalizeOutputPath,
-} from './utils/paths.js';
+} from './utils/paths';
 export {
   injectAssetTags,
   renderCodePageAsset,
   renderCopiedContentAsset,
   renderLiterateJavaPageAsset,
   renderPlainTextPageAsset,
-} from './utils/render.js';
-export { parseFrontMatter } from './utils/front-matter.js';
+} from './utils/render';
+export { parseFrontMatter } from './utils/front-matter';

package/build/utils/code.ts

@@ -1,11 +1,11 @@
 import MarkdownIt from 'markdown-it';
 import { parse as parseJava } from 'java-parser';
 import { JSDOM } from 'jsdom';
-import { makeLogger } from '../log.js';
-import { getHighlighter } from './shiki-highlighter.js';
-import externalLinksPlugin from '../external-links-plugin.js';
-import applyBasePathPlugin from '../apply-base-path-plugin.js';
-import type { JavaTocEntry, SiteVariables } from '../types.js';
+import { makeLogger } from '../log';
+import { getHighlighter } from './shiki-highlighter';
+import externalLinksPlugin from '../external-links-plugin';
+import applyBasePathPlugin from '../apply-base-path-plugin';
+import type { JavaTocEntry, SiteVariables } from '../types';
 
 interface CstNode {
   name?: string;

package/build/utils/content-files.ts

@@ -1,12 +1,12 @@
 import fs from 'fs';
 import path from 'path';
-import { parseFrontMatterAndContent } from './front-matter.js';
+import { parseFrontMatterAndContent } from './front-matter';
 import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
-} from './file-types.js';
-import { getPublicDir, normalizeOutputPath } from './paths.js';
+} from './file-types';
+import { getPublicDir, normalizeOutputPath } from './paths';
 
 function walkFiles(dir: string): string[] {
   return fs.readdirSync(dir).flatMap(file => {

package/build/utils/derive-theme.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 import { parse, oklch } from 'culori';
-import { deriveTheme, getTextOnColor } from './derive-theme.js';
+import { deriveTheme, getTextOnColor } from './derive-theme';
 
 function getL(hex: string): number {
   return oklch(parse(hex))!.l;

package/build/utils/derive-theme.ts

@@ -1,6 +1,6 @@
 import { parse, oklch, rgb, toGamut, formatHex } from 'culori';
 import type { Oklch, Rgb } from 'culori';
-import type { DerivedTheme } from '../types.js';
+import type { DerivedTheme } from '../types';
 
 // OKLCH lightness range for the theme color used as backgrounds/outlines
 const LIGHT_THEME_L_MIN = 0.35;

package/build/utils/file-types.test.ts

@@ -3,7 +3,7 @@ import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
-} from './file-types.js';
+} from './file-types';
 
 describe('getProcessedExtensions', () => {
   test('includes md, markdown, html, and custom extensions', () => {

package/build/utils/front-matter.test.ts

@@ -1,8 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import {
-  parseFrontMatterAndContent,
-  parseFrontMatter,
-} from './front-matter.js';
+import { parseFrontMatterAndContent, parseFrontMatter } from './front-matter';
 
 describe('parseFrontMatter', () => {
   test('parses markdown front matter separated by blank line', () => {

package/build/utils/front-matter.ts

@@ -1,6 +1,6 @@
 import fm from 'front-matter';
-import { extensionIsMarkdown } from './file-types.js';
-import type { ParsedContent } from '../types.js';
+import { extensionIsMarkdown } from './file-types';
+import type { ParsedContent } from '../types';
 
 interface RawParsedFrontMatter {
   frontMatter: string | null;

package/build/utils/literate-java.ts

@@ -1,16 +1,16 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { execSync } from 'child_process';
-import { createMarkdown } from './markdown.js';
-import { makeLogger } from '../log.js';
-import { parseFrontMatterAndContent } from './front-matter.js';
+import { execFileSync } from 'child_process';
+import { createMarkdown } from './markdown';
+import { makeLogger } from '../log';
+import { parseFrontMatterAndContent } from './front-matter';
 import type {
   SiteVariables,
   LiterateJavaParseResult,
   LiterateCodeBlock,
   LiterateRunnerEntry,
-} from '../types.js';
+} from '../types';
 
 const log = makeLogger(__filename);
 
@@ -88,7 +88,7 @@ export function compileJavaSource(
   log.debug`Compiling ${className}.java (${javaSource.split('\n').length} lines) in ${tempDir}`;
 
   try {
-    execSync(`javac "${className}.java"`, {
+    execFileSync('javac', [`${className}.java`], {
       cwd: tempDir,
       timeout: 30000,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -120,7 +120,7 @@ function ensureRunnerCompiled(runnerDir: string): void {
   log.debug`Compiling LiterateRunner.java`;
 
   try {
-    execSync('javac LiterateRunner.java', {
+    execFileSync('javac', ['LiterateRunner.java'], {
       cwd: runnerDir,
       timeout: 30000,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -150,8 +150,9 @@ export function executeLiterateJava(
   log.debug`Running LiterateRunner with ${blockRanges.length} block range(s)`;
 
   try {
-    const result = execSync(
-      `java -cp "${runnerDir}" LiterateRunner "${className}" "${classPath}" '${rangesJson}'`,
+    const result = execFileSync(
+      'java',
+      ['-cp', runnerDir, 'LiterateRunner', className, classPath, rangesJson],
       { timeout: 30000, encoding: 'utf-8' },
     );
     const entries: LiterateRunnerEntry[] = JSON.parse(result);
@@ -174,7 +175,7 @@ export function executeLiterateJava(
 
 export function checkJavac(): boolean {
   try {
-    execSync('javac -version', { stdio: ['pipe', 'pipe', 'pipe'] });
+    execFileSync('javac', ['-version'], { stdio: ['pipe', 'pipe', 'pipe'] });
     return true;
   } catch {
     return false;

package/build/utils/markdown.ts

@@ -7,15 +7,18 @@ import markdownItAnchor from 'markdown-it-anchor';
 import markdownItFootnote from 'markdown-it-footnote';
 import markdownItDeflist from 'markdown-it-deflist';
 import markdownItContainer from 'markdown-it-container';
-import textToId from '../text-to-id.js';
-import { getHighlighter } from './shiki-highlighter.js';
-import headingSubtitlePlugin from '../heading-subtitle-plugin.js';
-import deflistIdPlugin from '../deflist-id-plugin.js';
-import externalLinksPlugin from '../external-links-plugin.js';
-import validateInternalLinksPlugin from '../validate-internal-links-plugin.js';
-import applyBasePathPlugin from '../apply-base-path-plugin.js';
-import { tocPlugin } from '../toc-plugin.js';
-import type { SiteVariables } from '../types.js';
+import textToId from '../text-to-id';
+import { getHighlighter } from './shiki-highlighter';
+import headingSubtitlePlugin from '../heading-subtitle-plugin';
+import deflistIdPlugin from '../deflist-id-plugin';
+import externalLinksPlugin from '../external-links-plugin';
+import validateInternalLinksPlugin from '../validate-internal-links-plugin';
+import applyBasePathPlugin from '../apply-base-path-plugin';
+import { tocPlugin } from '../toc-plugin';
+import markdownItKatex from '@vscode/markdown-it-katex';
+import katex from 'katex';
+import renderA11yString from 'katex/contrib/render-a11y-string';
+import type { SiteVariables } from '../types';
 
 interface CreateMarkdownOptions {
   validatorOptions?: Record<string, unknown>;
@@ -44,6 +47,7 @@ export function createMarkdown(
     .use(validateInternalLinksPlugin, validatorOptions)
     .use(applyBasePathPlugin, siteVariables)
     .use(tocPlugin)
+    .use(markdownItKatex)
     .use(markdownItContainer, 'details', {
       marker: '<',
       validate: function (params: string) {
@@ -78,6 +82,34 @@ export function createMarkdown(
       },
     });
 
+  // The @vscode/markdown-it-katex plugin's renderers swallow errors thrown
+  // by katex.renderToString() and return error HTML instead of propagating
+  // the exception. Override the renderers so parse errors fail the build.
+  // The plugin's tokenizer ($ and $$ delimiter parsing) is kept.
+  // Each renderer also adds an aria-label with a screen-reader-friendly
+  // description generated by katex/contrib/render-a11y-string.
+  markdown.renderer.rules.math_inline = (tokens: Token[], idx: number) => {
+    const latex = tokens[idx].content;
+    const html = katex.renderToString(latex, { throwOnError: true });
+    const a11y = markdown.utils.escapeHtml(renderA11yString(latex));
+    return html.replace(
+      '<span class="katex">',
+      `<span class="katex" aria-label="${a11y}">`,
+    );
+  };
+  const katexBlockRenderer = (tokens: Token[], idx: number) => {
+    const latex = tokens[idx].content;
+    const html = katex.renderToString(latex, {
+      throwOnError: true,
+      displayMode: true,
+    });
+    const a11y = markdown.utils.escapeHtml(renderA11yString(latex));
+    return `<p class="katex-block" aria-label="${a11y}">` + html + `</p>\n`;
+  };
+  markdown.renderer.rules.math_block = katexBlockRenderer;
+  markdown.renderer.rules.math_inline_block = katexBlockRenderer;
+  markdown.renderer.rules.math_inline_bare_block = katexBlockRenderer;
+
   const usedIds = new Map<string, number>();
   markdown.use(markdownItContainer, 'alert', {
     marker: '!',

package/build/utils/paths.test.ts

@@ -9,8 +9,8 @@ import {
   getConfigDir,
   createApplyBasePath,
   normalizeOutputPath,
-} from './paths.js';
-import type { SiteVariables } from '../types.js';
+} from './paths';
+import type { SiteVariables } from '../types';
 
 describe('getPackageDir', () => {
   test('returns an absolute path', () => {

package/build/utils/paths.ts

@@ -1,5 +1,5 @@
 import path from 'path';
-import type { SiteVariables } from '../types.js';
+import type { SiteVariables } from '../types';
 
 export function getPackageDir(): string {
   return path.resolve(__dirname, '..', '..');
@@ -17,6 +17,10 @@ export function getDistDir(): string {
   return path.resolve(getProjectDir(), 'dist');
 }
 
+export function getProdDistDir(): string {
+  return path.resolve(getProjectDir(), 'dist-prod');
+}
+
 export function getPublicDir(): string {
   return path.resolve(getProjectDir(), 'public');
 }

package/build/utils/render.ts

@@ -2,31 +2,28 @@ import fs from 'fs';
 import path from 'path';
 import _ from 'lodash';
 import { stripHtml } from 'string-strip-html';
-import { makeLogger } from '../log.js';
-import { B } from '../colors.js';
-import createGlobals from '../globals.js';
-import { render, json } from '../templates.js';
+import { isFeatureEnabled } from '../features';
+import { makeLogger } from '../log';
+import { B } from '../colors';
+import createGlobals from '../globals';
+import { render, json } from '../templates';
 import {
   extractJavaMethodToc,
   renderCodeSegment,
   renderCodeWithComments,
-} from './code.js';
-import { extensionIsMarkdown } from './file-types.js';
-import {
-  createApplyBasePath,
-  normalizeOutputPath,
-  getDistDir,
-} from './paths.js';
-import { parseFrontMatterAndContent } from './front-matter.js';
-import { createMarkdown } from './markdown.js';
-import { generateTocHtml, generateCodeTocHtml } from '../toc-plugin.js';
+} from './code';
+import { extensionIsMarkdown } from './file-types';
+import { createApplyBasePath, normalizeOutputPath } from './paths';
+import { parseFrontMatterAndContent } from './front-matter';
+import { createMarkdown } from './markdown';
+import { generateTocHtml, generateCodeTocHtml } from '../toc-plugin';
 import {
   parseLiterateJava,
   hasMainMethod,
   deriveClassName,
   compileJavaSource,
   executeLiterateJava,
-} from './literate-java.js';
+} from './literate-java';
 import type {
   Asset,
   SiteVariables,
@@ -34,7 +31,7 @@ import type {
   RenderCodePageOptions,
   RenderLiterateJavaOptions,
   RenderCopiedContentOptions,
-} from '../types.js';
+} from '../types';
 
 const log = makeLogger(__filename);
 
@@ -112,6 +109,7 @@ 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'));
@@ -121,8 +119,6 @@ export function injectAssetTags(
     .join('');
   const criticalAssets = cssAssets.filter(f => f.includes('critical.bundle.'));
   const asyncAssets = cssAssets.filter(f => !f.includes('critical.bundle.'));
-
-  const distDir = getDistDir();
   const criticalTags = criticalAssets
     .map(asset => {
       const css = fs.readFileSync(path.join(distDir, asset), 'utf-8');
@@ -142,6 +138,17 @@ 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" media="print" onload="this.media='all'">` +
+    `<noscript><link href="${href}" rel="stylesheet"></noscript>`;
+  return html.replace('<head>', `<head>${tag}`);
+}
+
 function toContentAssetPath(contentDir: string, filePath: string): string {
   return path
     .relative(contentDir, filePath)
@@ -152,6 +159,7 @@ function toContentAssetPath(contentDir: string, filePath: string): string {
 export function renderPlainTextPageAsset({
   filePath,
   contentDir,
+  distDir,
   siteVariables,
   validInternalTargets,
   assetFiles,
@@ -190,11 +198,14 @@ export function renderPlainTextPageAsset({
     subPath,
   });
 
-  const html = injectAssetTags(
-    render(`${pageVariables.template}.html`, templateParameters) as string,
-    assetFiles,
-    applyBasePath,
-  );
+  const templateHtml = render(
+    `${pageVariables.template}.html`,
+    templateParameters,
+  ) as string;
+  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
+  if (templateHtml.includes('class="katex"')) {
+    html = injectKatexStylesheet(html, applyBasePath);
+  }
 
   return [
     {
@@ -207,6 +218,7 @@ export function renderPlainTextPageAsset({
 export function renderCodePageAsset({
   filePath,
   contentDir,
+  distDir,
   siteVariables,
   assetFiles,
 }: RenderCodePageOptions): Asset[] {
@@ -247,6 +259,7 @@ export function renderCodePageAsset({
     render('code.html', templateParameters) as string,
     assetFiles,
     applyBasePath,
+    distDir,
   );
 
   return [
@@ -288,10 +301,9 @@ function renderPlainTextContent(
       filePath,
       sourceUrlPath,
       validTargets: validInternalTargets,
-      codeExtensions:
-        siteVariables.features?.code === false
-          ? []
-          : Object.keys(siteVariables.codeLanguages!),
+      codeExtensions: isFeatureEnabled(siteVariables, 'code')
+        ? Object.keys(siteVariables.codeLanguages!)
+        : [],
     },
   });
 
@@ -381,6 +393,7 @@ export function stripHtmlComments(str: string): string {
 export function renderLiterateJavaPageAsset({
   filePath,
   contentDir,
+  distDir,
   siteVariables,
   assetFiles,
   skipExecution,
@@ -509,11 +522,11 @@ export function renderLiterateJavaPageAsset({
     subPath,
   });
 
-  const html = injectAssetTags(
-    render('literate.html', templateParameters) as string,
-    assetFiles,
-    applyBasePath,
-  );
+  const templateHtml = render('literate.html', templateParameters) as string;
+  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
+  if (templateHtml.includes('class="katex"')) {
+    html = injectKatexStylesheet(html, applyBasePath);
+  }
 
   return [
     {

package/build/utils/shiki-highlighter.ts

@@ -1,5 +1,5 @@
 import type { HighlighterGeneric, BundledLanguage, BundledTheme } from 'shiki';
-import { makeLogger } from '../log.js';
+import { makeLogger } from '../log';
 
 const log = makeLogger(__filename);
 

package/build/validate-internal-links-plugin.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 import MarkdownIt from 'markdown-it';
-import validateInternalLinks from './validate-internal-links-plugin.js';
+import validateInternalLinks from './validate-internal-links-plugin';
 
 function createMd(
   validTargets: string[],

package/build/validate-internal-links-plugin.ts

@@ -1,7 +1,7 @@
 import type MarkdownIt from 'markdown-it';
 import type Token from 'markdown-it/lib/token.mjs';
 import path from 'path';
-import { makeLogger } from './log.js';
+import { makeLogger } from './log';
 
 const log = makeLogger(__filename);
 

package/build/watch-reachability-state.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
-import { collectReachableSiteAssets } from './reachability.js';
-import WatchReachabilityState from './watch-reachability-state.js';
+import { collectReachableSiteAssets } from './reachability';
+import WatchReachabilityState from './watch-reachability-state';
 
 function createReader(htmlByPath: Map<string, string>) {
   const calls: string[] = [];

package/build/watch-reachability-state.ts

@@ -1,4 +1,4 @@
-import { collectDirectSiteAssetLinks } from './reachability.js';
+import { collectDirectSiteAssetLinks } from './reachability';
 
 type ReadHtmlForAsset = (assetPath: string) => string;