@abreen/tada 1.0.0

package/webpack/generate-manifest-plugin.js

@@ -0,0 +1,116 @@
+const { createApplyBasePath } = require('./util');
+
+class GenerateManifestPlugin {
+  constructor(siteVariables) {
+    this.siteVariables = siteVariables || {};
+  }
+
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap(
+      'GenerateManifestPlugin',
+      compilation => {
+        const wp = compilation.compiler.webpack || {};
+        const { RawSource } =
+          (wp.sources && wp.sources) || require('webpack-sources');
+
+        compilation.hooks.processAssets.tapPromise(
+          {
+            name: 'GenerateManifestPlugin',
+            stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
+          },
+          async () => {
+            try {
+              const manifest = createManifest(this.siteVariables);
+              const output = JSON.stringify(manifest);
+              compilation.emitAsset('manifest.json', new RawSource(output));
+            } catch (err) {
+              compilation.errors.push(
+                new Error(`Error: ${err && err.message ? err.message : err}`),
+              );
+            }
+          },
+        );
+      },
+    );
+  }
+}
+
+module.exports = GenerateManifestPlugin;
+
+function createManifest(siteVariables) {
+  const applyBasePath = createApplyBasePath(siteVariables);
+
+  return {
+    name: siteVariables.title,
+    start_url: applyBasePath('/index.html'),
+    display: 'minimal-ui',
+    icons: [
+      {
+        src: 'favicon.svg',
+        sizes: 'any',
+        type: 'image/svg+xml',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-1024.png',
+        sizes: '1024x1024',
+        type: 'image/png',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-512.png',
+        sizes: '512x512',
+        type: 'image/png',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-256.png',
+        sizes: '256x256',
+        type: 'image/png',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-192.png',
+        sizes: '192x192',
+        type: 'image/png',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-128.png',
+        sizes: '128x128',
+        type: 'image/png',
+        purpose: 'any maskable',
+      },
+      {
+        src: 'favicon-64.png',
+        sizes: '64x64',
+        type: 'image/png',
+        purpose: 'any',
+      },
+      {
+        src: 'favicon-48.png',
+        sizes: '48x48',
+        type: 'image/png',
+        purpose: 'any',
+      },
+      {
+        src: 'favicon-32.png',
+        sizes: '32x32',
+        type: 'image/png',
+        purpose: 'any',
+      },
+      {
+        src: 'favicon-16.png',
+        sizes: '16x16',
+        type: 'image/png',
+        purpose: 'any',
+      },
+      {
+        src: 'favicon.ico',
+        sizes: '16x16 32x32 48x48 64x64 128x128 192x192 256x256',
+        type: 'image/x-icon',
+        purpose: 'any maskable',
+      },
+    ],
+  };
+}

package/webpack/globals.js

@@ -0,0 +1,74 @@
+const timezones = require('../src/timezone/timezones.json');
+
+module.exports = function createGlobals(site, page, subPath) {
+  const siteVars = page; // second arg receives siteVariables per render.js call convention
+  const defaultTz = timezones.find(t => t.value === siteVars.defaultTimeZone);
+  const timezoneChooser = defaultTz
+    ? `<select class="time-zone" hidden></select><noscript>Times shown in ${defaultTz.abbreviation}.</noscript>`
+    : '<select class="time-zone" hidden></select>';
+
+  return {
+    isHomePage: subPath === 'index',
+    isoDate,
+    readableDate,
+    classNames,
+    cx: classNames,
+    timezoneChooser,
+  };
+};
+
+function isoDate(str) {
+  if (str == null || str == '') {
+    return null;
+  }
+  const date = new Date(str);
+  return date.toISOString().slice(0, 10);
+}
+
+function readableDate(date) {
+  if (date == null || date == '') {
+    return '';
+  }
+
+  if (!(date instanceof Date)) {
+    date = new Date(date);
+  }
+
+  const str = date.toISOString();
+  const year = str.slice(0, 4);
+  let month = str.slice(5, 7);
+  if (month[0] === '0') {
+    month = month[1];
+  }
+  let day = str.slice(8, 10);
+  if (day[0] === '0') {
+    day = day[1];
+  }
+
+  const months = {
+    1: 'January',
+    2: 'February',
+    3: 'March',
+    4: 'April',
+    5: 'May',
+    6: 'June',
+    7: 'July',
+    8: 'August',
+    9: 'September',
+    10: 'October',
+    11: 'November',
+    12: 'December',
+  };
+
+  return `${months[month]} ${day}, ${year}`;
+}
+
+function classNames(obj) {
+  const names = [];
+  for (const key in obj) {
+    if (!!obj[key]) {
+      names.push(key);
+    }
+  }
+  return names.join(' ');
+}

package/webpack/heading-subtitle-plugin.js

@@ -0,0 +1,80 @@
+module.exports = function specialHeadingsPlugin(md) {
+  md.core.ruler.push('special_headings', state => {
+    const tokens = state.tokens;
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].type !== 'heading_open') {
+        continue;
+      }
+
+      // Expected structure: heading_open -> inline -> heading_close
+      const inline = tokens[i + 1];
+      const close = tokens[i + 2];
+      if (
+        !inline ||
+        inline.type !== 'inline' ||
+        !close ||
+        close.type !== 'heading_close'
+      ) {
+        continue;
+      }
+
+      const original = inline.content;
+      // Match: <main> # <subtitle>
+      const parts = original.split(/ # /);
+      if (parts.length < 2) {
+        continue;
+      }
+
+      const main = parts.shift();
+      const subtitle = parts.join(' # ').trim();
+      if (!main || !subtitle) {
+        continue;
+      }
+
+      // Find the delimiter " # " inside child text tokens to wrap the remainder
+      if (Array.isArray(inline.children)) {
+        for (let ci = 0; ci < inline.children.length; ci++) {
+          const child = inline.children[ci];
+          if (child.type !== 'text') {
+            continue;
+          }
+          const sepIndex = child.content.indexOf(' # ');
+          if (sepIndex === -1) {
+            continue;
+          }
+
+          // Split the text token around the first " # "
+          const before = child.content.slice(0, sepIndex).trimEnd();
+          const afterPart = child.content.slice(sepIndex + 3); // skip " # "
+          child.content = before + ' '; // ensure a single space before subtitle
+
+          // Collect subtitle tokens: (afterPart as text, plus all following siblings)
+          const subtitleTokens = [];
+          if (afterPart) {
+            const t = new state.Token('text', '', 0);
+            t.content = afterPart;
+            subtitleTokens.push(t);
+          }
+          for (let k = ci + 1; k < inline.children.length; k++) {
+            subtitleTokens.push(inline.children[k]);
+          }
+
+          // Truncate children after the (modified) delimiter text token
+          inline.children.length = ci + 1;
+
+          // Inject span wrapper with preserved formatting tokens
+          const openSpan = new state.Token('html_inline', '', 0);
+          openSpan.content = '<span class="heading-subtitle">';
+          const closeSpan = new state.Token('html_inline', '', 0);
+          closeSpan.content = '</span>';
+          inline.children.push(openSpan, ...subtitleTokens, closeSpan);
+          break;
+        }
+      }
+
+      // Update inline.content (plain text representation)
+      inline.content = `${main} ${subtitle}`;
+      tokens[i].attrJoin('class', 'has-subtitle');
+    }
+  });
+};

package/webpack/json-schema.js

@@ -0,0 +1,19 @@
+const JsonSchemaCompiler = require('ajv');
+
+const compiler = new JsonSchemaCompiler();
+
+function compile(schema) {
+  return compiler.compile(schema);
+}
+
+function doValidation(validator, input, fileName) {
+  const valid = validator(input);
+  if (!valid) {
+    validator.errors.forEach(error => {
+      console.error(error);
+    });
+    throw new Error(`JSON file failed validation: ${fileName}`);
+  }
+}
+
+module.exports = { compile, doValidation };

package/webpack/log.js

@@ -0,0 +1,143 @@
+const { inspect } = require('node:util');
+const path = require('path');
+const { G, R, P, Y, L } = require('./colors');
+const FLAIR_STRINGS = require('./flair.json');
+
+const LEVELS = ['debug', 'info', 'warn', 'error'];
+
+const ENV_LOG_LEVEL = process.env.TADA_LOG_LEVEL;
+
+if (ENV_LOG_LEVEL && !LEVELS.includes(ENV_LOG_LEVEL)) {
+  throw new Error(
+    `Invalid TADA_LOG_LEVEL "${ENV_LOG_LEVEL}", must be one of: ${LEVELS.join(', ')}`,
+  );
+}
+
+function shouldLog(loggerLevel, level) {
+  return LEVELS.indexOf(level) >= LEVELS.indexOf(loggerLevel);
+}
+
+function validateLevel(level) {
+  if (!LEVELS.includes(level)) {
+    throw new Error(
+      `Invalid log level "${level}", must be one of: ${LEVELS.join(', ')}`,
+    );
+  }
+}
+
+function print(strings, stream = 'stdout', end = '\n') {
+  for (const s of strings) {
+    process[stream].write(s);
+  }
+  process[stream].write(end);
+}
+
+function makeLogger(name, logLevel = 'info') {
+  validateLevel(logLevel);
+
+  if (ENV_LOG_LEVEL) {
+    logLevel = ENV_LOG_LEVEL;
+  }
+
+  if (!name) {
+    name = '';
+  } else {
+    // Allow for passing __filename
+    name = path.basename(name);
+  }
+
+  const logger = {
+    /** Don't log if the level is < minLogLevel */
+    setMinLogLevel(minLogLevel) {
+      this.minLogLevel = minLogLevel;
+    },
+    getArgs(level, strings, args, colorFn) {
+      const params = [];
+      params.push(colorFn`${level}` + '\t');
+      params.push(format(strings, ...args));
+      return params;
+    },
+    debug(strings, ...args) {
+      if (shouldLog(this.minLogLevel, 'debug')) {
+        print(this.getArgs('debug', strings, args, L), 'stderr');
+      }
+    },
+    info(strings, ...args) {
+      if (shouldLog(this.minLogLevel, 'info')) {
+        print(this.getArgs('info', strings, args, L));
+      }
+    },
+    warn(strings, ...args) {
+      if (shouldLog(this.minLogLevel, 'warn')) {
+        print(this.getArgs('warn', strings, args, Y));
+      }
+    },
+    error(strings, ...args) {
+      if (shouldLog(this.minLogLevel, 'error')) {
+        print(this.getArgs('error', strings, args, R));
+      }
+    },
+    event(strings, ...args) {
+      print(this.getArgs('event', strings, args, G));
+    },
+    followup(strings) {
+      print(strings);
+    },
+  };
+
+  logger.setMinLogLevel(logLevel);
+  return logger;
+}
+
+function format(strings, ...args) {
+  // Called as template tag: first arg is an array-like with .raw
+  if (strings && typeof strings === 'object' && 'raw' in strings) {
+    try {
+      return String.raw(strings, ...args.map(toString));
+    } catch (e) {
+      // fallback to safe join
+    }
+  } else {
+    if (Array.isArray(strings)) {
+      args.unshift(...strings);
+    } else {
+      args.unshift(strings);
+    }
+
+    return args.map(toString).join(' ');
+  }
+}
+
+function toString(item) {
+  if (item === undefined) {
+    return 'undefined';
+  }
+  if (item === null) {
+    return 'null';
+  }
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  try {
+    if (typeof item === 'object') {
+      return inspect(item, {
+        compact: true,
+        depth: 2,
+        breakLength: 80,
+        maxStringLength: 250,
+        colors: true,
+      });
+    }
+    throw new Error('not an object');
+  } catch (e) {
+    return String(item);
+  }
+}
+
+function getFlair() {
+  const i = Math.floor(Math.random() * FLAIR_STRINGS.length);
+  return P`${FLAIR_STRINGS[i]}!` + ' 🎉';
+}
+
+module.exports = { makeLogger, getFlair };

package/webpack/markdown-plugins.test.js

@@ -0,0 +1,203 @@
+const { describe, expect, test } = require('bun:test');
+const MarkdownIt = require('markdown-it');
+const deflist = require('markdown-it-deflist');
+const applyBasePathPlugin = require('./apply-base-path-plugin');
+const deflistIdPlugin = require('./deflist-id-plugin');
+const externalLinksPlugin = require('./external-links-plugin');
+const headingSubtitlePlugin = require('./heading-subtitle-plugin');
+const { createMarkdown } = require('./utils/markdown');
+
+describe('apply-base-path-plugin', () => {
+  test('rewrites internal links, images, and raw html image sources', () => {
+    const md = new MarkdownIt({ html: true });
+    md.use(applyBasePathPlugin, {
+      basePath: '/course/',
+      codeLanguages: { java: 'java' },
+      features: { code: true },
+    });
+
+    const html = md.render(
+      [
+        '[Code](/src/example.java?view=1#top)',
+        '',
+        '![Image](/images/pic.png)',
+        '',
+        '<img src="/images/raw.png" alt="Raw">',
+      ].join('\n'),
+    );
+
+    expect(html).toContain('href="/course/src/example.html?view=1#top"');
+    expect(html).toContain('src="/course/images/pic.png"');
+    expect(html).toContain('src="/course/images/raw.png"');
+  });
+
+  test('rewrites relative code file links without applying base path', () => {
+    const md = new MarkdownIt();
+    md.use(applyBasePathPlugin, {
+      basePath: '/course/',
+      codeLanguages: { java: 'java' },
+      features: { code: true },
+    });
+
+    const html = md.render('[App](./App.java)');
+
+    expect(html).toContain('href="./App.html"');
+    expect(html).not.toContain('href="./App.java"');
+  });
+
+  test('keeps code file extensions when the code feature is disabled', () => {
+    const md = new MarkdownIt();
+    md.use(applyBasePathPlugin, {
+      basePath: '/course',
+      codeLanguages: { java: 'java' },
+      features: { code: false },
+    });
+
+    const html = md.render('[Code](/src/example.java#L1)');
+
+    expect(html).toContain('href="/course/src/example.java#L1"');
+    expect(html).not.toContain('href="/course/src/example.html#L1"');
+  });
+});
+
+describe('external-links-plugin', () => {
+  test('marks external http links without changing internal or non-http links', () => {
+    const md = new MarkdownIt();
+    md.use(externalLinksPlugin, { internalDomains: ['example.com'] });
+
+    const html = md.render(
+      [
+        '[External](https://outside.example/docs)',
+        '[Internal](https://example.com/docs)',
+        '[Mail](mailto:test@example.com)',
+      ].join(' '),
+    );
+
+    expect(html).toContain(
+      '<a href="https://outside.example/docs" class="external" target="_blank">External</a>',
+    );
+    expect(html).toContain('<a href="https://example.com/docs">Internal</a>');
+    expect(html).toContain('<a href="mailto:test@example.com">Mail</a>');
+  });
+});
+
+describe('heading-subtitle-plugin', () => {
+  test('wraps heading subtitles while preserving inline formatting', () => {
+    const md = new MarkdownIt();
+    md.use(headingSubtitlePlugin);
+
+    const html = md.render('## Title # *Subtitle*').trim();
+
+    expect(html).toBe(
+      '<h2 class="has-subtitle">Title <span class="heading-subtitle"><em>Subtitle</em></span></h2>',
+    );
+  });
+});
+
+describe('deflist-id-plugin', () => {
+  test('injects unique ids for terms and falls back when a term slug is empty', () => {
+    const md = new MarkdownIt();
+    md.use(deflist);
+    md.use(deflistIdPlugin);
+
+    const html = md.render(
+      ['Term 1', ': One', '', 'Term 1', ': Two', '', '!!!', ': Three'].join(
+        '\n',
+      ),
+    );
+
+    expect(html).toContain('<a id="term-1"></a>Term 1');
+    expect(html).toContain('<a id="term-1-2"></a>Term 1');
+    expect(html).toContain('<a id="term"></a>!!!');
+  });
+});
+
+describe('custom markdown containers', () => {
+  function createProjectMarkdown() {
+    return createMarkdown(
+      { basePath: '/', internalDomains: [], codeLanguages: {}, features: {} },
+      { validatorOptions: { enabled: false } },
+    );
+  }
+
+  test('renders collapsible details blocks', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      ['<<< details More info', 'Hello', '<<<'].join('\n'),
+    );
+
+    expect(html).toContain('<details><summary>More info</summary>');
+    expect(html).toContain('<div class="content">');
+    expect(html).toContain('<p>Hello</p>');
+    expect(html).toContain('</div></details>');
+  });
+
+  test('renders collapsible details blocks with inline Markdown in summary', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      ['<<< details More **info**', 'Hello', '<<<'].join('\n'),
+    );
+
+    expect(html).toContain(
+      '<details><summary>More <strong>info</strong></summary>',
+    );
+  });
+
+  test('renders section containers as section elements', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(['::: section', 'Body', ':::'].join('\n'));
+
+    expect(html).toContain('<section>');
+    expect(html).toContain('<p>Body</p>');
+    expect(html).toContain('</section>');
+  });
+
+  test('renders questions with question and spoiler answer', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      [
+        '??? question What is a data structure?',
+        'An organized collection.',
+        '???',
+      ].join('\n'),
+    );
+
+    expect(html).toContain('<div class="question">');
+    expect(html).toContain(
+      '<p class="question-q"><span class="question-label">Q.</span><span>What is a data structure?</span></p>',
+    );
+    expect(html).toContain('<p class="question-a-label">A.</p>');
+    expect(html).toContain(
+      '<div class="question-a-body" data-pagefind-ignore>',
+    );
+    expect(html).toContain('<p>An organized collection.</p>');
+  });
+
+  test('renders alert containers with custom and default titles', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      [
+        '!!! note "Read this"',
+        'Body',
+        '!!!',
+        '',
+        '!!! warning',
+        'Careful',
+        '!!!',
+      ].join('\n'),
+    );
+
+    expect(html).toContain('<div class="alert note">');
+    expect(html).toContain('<p class="title" id="read-this">');
+    expect(html).toContain(
+      '<div class="alert warning"><p class="title">Warning</p>',
+    );
+    expect(html).toContain('<p>Body</p>');
+    expect(html).toContain('<p>Careful</p>');
+  });
+});