@abreen/tada 1.11.2 → 1.13.2

package/build/utils/final-html.ts

@@ -0,0 +1,239 @@
+import path from 'path';
+import { JSDOM } from 'jsdom';
+import { getExtensionToShikiLanguage } from '../site-variables';
+import { createApplyBasePath, normalizeOutputPath } from './paths';
+import { isInternalLink } from './link';
+import type {
+  HtmlOutputAnalysis,
+  RenderDependencyCollector,
+  SiteVariables,
+} from '../types';
+
+interface FinalizeHtmlPageOptions {
+  filePath: string;
+  html: string;
+  siteVariables: SiteVariables;
+  sourceUrlPath: string;
+  validInternalTargets: Set<string>;
+  literateJavaOutputPaths?: Set<string>;
+  dependencyCollector?: RenderDependencyCollector;
+}
+
+interface FinalizedHtmlPage {
+  html: string;
+  analysis: HtmlOutputAnalysis;
+}
+
+function splitHref(href: string): { pathname: string; suffix: string } {
+  const match = href.match(/^([^?#]*)(.*)$/);
+  return { pathname: match ? match[1] : href, suffix: match ? match[2] : '' };
+}
+
+function resolvePathname(
+  sourceUrlPath: string,
+  pathname: string,
+): string | null {
+  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;
+  }
+}
+
+function getDirectoryIndexPath(pathname: string): string {
+  return normalizeOutputPath(path.posix.join(pathname, 'index.html'));
+}
+
+function hasMappedCodeExtension(
+  pathname: string,
+  codeExtensions: string[],
+): boolean {
+  const lower = pathname.toLowerCase();
+  return codeExtensions.some(ext => lower.endsWith(`.${ext.toLowerCase()}`));
+}
+
+function rewriteAbsoluteHrefWithBasePath(
+  href: string,
+  applyBasePath: (subPath: string) => string,
+): string {
+  const { pathname, suffix } = splitHref(href);
+  if (!pathname.startsWith('/') || pathname.startsWith('//')) {
+    return href;
+  }
+  return `${applyBasePath(pathname)}${suffix}`;
+}
+
+function rewriteAbsoluteSrcWithBasePath(
+  src: string,
+  applyBasePath: (subPath: string) => string,
+): string {
+  if (!src.startsWith('/') || src.startsWith('//')) {
+    return src;
+  }
+  return applyBasePath(src);
+}
+
+function resolveAnchorTarget({
+  href,
+  sourceUrlPath,
+  validInternalTargets,
+  codeExtensions,
+  literateJavaOutputPaths,
+  skipCodeLinkRewrite,
+}: {
+  href: string;
+  sourceUrlPath: string;
+  validInternalTargets: Set<string>;
+  codeExtensions: string[];
+  literateJavaOutputPaths?: Set<string>;
+  skipCodeLinkRewrite: boolean;
+}): { finalHref: string; resolvedTarget: string | null } {
+  if (!isInternalLink(href)) {
+    return { finalHref: href, resolvedTarget: null };
+  }
+
+  const { pathname, suffix } = splitHref(href);
+  const resolvedPath = resolvePathname(sourceUrlPath, pathname);
+  if (!resolvedPath) {
+    return { finalHref: href, resolvedTarget: null };
+  }
+
+  let finalPathname = pathname;
+  let resolvedTarget = resolvedPath;
+  const mappedCodePath =
+    !skipCodeLinkRewrite && hasMappedCodeExtension(pathname, codeExtensions);
+
+  if (mappedCodePath) {
+    const htmlTarget = `${resolvedPath}.html`;
+    if (literateJavaOutputPaths?.has(resolvedPath)) {
+      resolvedTarget = resolvedPath;
+    } else if (validInternalTargets.has(htmlTarget)) {
+      finalPathname = `${pathname}.html`;
+      resolvedTarget = htmlTarget;
+    } else if (validInternalTargets.has(resolvedPath)) {
+      resolvedTarget = resolvedPath;
+    } else {
+      resolvedTarget = htmlTarget;
+    }
+  }
+
+  return { finalHref: `${finalPathname}${suffix}`, resolvedTarget };
+}
+
+export function finalizeHtmlPage({
+  filePath,
+  html,
+  siteVariables,
+  sourceUrlPath,
+  validInternalTargets,
+  literateJavaOutputPaths,
+  dependencyCollector,
+}: FinalizeHtmlPageOptions): FinalizedHtmlPage {
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const applyBasePath = createApplyBasePath(siteVariables);
+  const codeExtensions = Object.keys(
+    getExtensionToShikiLanguage(siteVariables),
+  );
+  const analysis: HtmlOutputAnalysis = { outgoingTargets: new Set() };
+
+  for (const element of document.querySelectorAll('[href]')) {
+    const href = element.getAttribute('href');
+    if (!href) {
+      continue;
+    }
+
+    const isAnchor = element.tagName === 'A';
+    const isContentAnchor = isAnchor && element.closest('main.body') !== null;
+
+    if (isContentAnchor) {
+      const { finalHref, resolvedTarget } = resolveAnchorTarget({
+        href,
+        sourceUrlPath,
+        validInternalTargets,
+        codeExtensions,
+        literateJavaOutputPaths,
+        skipCodeLinkRewrite: element.hasAttribute('download'),
+      });
+      const rewrittenHref = finalHref.startsWith('/')
+        ? rewriteAbsoluteHrefWithBasePath(finalHref, applyBasePath)
+        : finalHref;
+
+      if (rewrittenHref !== href) {
+        element.setAttribute('href', rewrittenHref);
+      }
+
+      if (resolvedTarget) {
+        if (isAnchor) {
+          analysis.outgoingTargets.add(resolvedTarget);
+        }
+
+        const directoryIndexPath = getDirectoryIndexPath(resolvedTarget);
+        if (
+          directoryIndexPath !== resolvedTarget &&
+          validInternalTargets.has(directoryIndexPath)
+        ) {
+          throw new Error(
+            `${filePath}: directory link must reference index.html explicitly: "${href}" (resolved to "${resolvedTarget}", expected "${directoryIndexPath}")`,
+          );
+        }
+
+        if (!validInternalTargets.has(resolvedTarget)) {
+          throw new Error(
+            `${filePath}: broken internal link: "${href}" (resolved to "${resolvedTarget}")`,
+          );
+        }
+
+        dependencyCollector?.internalTargets?.add(resolvedTarget);
+      }
+
+      continue;
+    }
+
+    if (isAnchor && isInternalLink(href)) {
+      const { pathname } = splitHref(href);
+      const resolvedTarget = resolvePathname(sourceUrlPath, pathname);
+      if (resolvedTarget) {
+        analysis.outgoingTargets.add(resolvedTarget);
+      }
+    }
+
+    const rewrittenHref = rewriteAbsoluteHrefWithBasePath(href, applyBasePath);
+    if (rewrittenHref !== href) {
+      element.setAttribute('href', rewrittenHref);
+    }
+  }
+
+  for (const element of document.querySelectorAll('[src]')) {
+    const src = element.getAttribute('src');
+    if (!src) {
+      continue;
+    }
+
+    const rewrittenSrc = rewriteAbsoluteSrcWithBasePath(src, applyBasePath);
+    if (rewrittenSrc !== src) {
+      element.setAttribute('src', rewrittenSrc);
+    }
+  }
+
+  const doctype = document.doctype;
+  const doctypePrefix = doctype
+    ? `<!DOCTYPE ${doctype.name}${
+        doctype.publicId ? ` PUBLIC "${doctype.publicId}"` : ''
+      }${doctype.systemId ? ` "${doctype.systemId}"` : ''}>`
+    : '';
+
+  return {
+    html: `${doctypePrefix}${document.documentElement.outerHTML}`,
+    analysis,
+  };
+}

package/build/utils/markdown.ts

@@ -1,6 +1,6 @@
 import MarkdownIt from 'markdown-it';
 import type { Options } from 'markdown-it/lib/index.mjs';
-import type Token from 'markdown-it/lib/token.mjs';
+import Token from 'markdown-it/lib/token.mjs';
 import type Renderer from 'markdown-it/lib/renderer.mjs';
 import { convertMarkdown as curlyQuote } from 'quote-quote';
 import markdownItAnchor from 'markdown-it-anchor';
@@ -13,8 +13,6 @@ import { isBundledLanguage, isPlainTextLanguage } from '../site-variables';
 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 columnsPlugin from '../columns-plugin';
 import markdownItKatex from '@vscode/markdown-it-katex';
@@ -27,8 +25,9 @@ const ALERT_PATTERN = /^(note|warning)(?:\s+"(.+)"|\s+(.+))?$/;
 const QUESTION_PATTERN = /^question\s+(.+)$/;
 
 interface CreateMarkdownOptions {
-  validatorOptions?: Record<string, unknown>;
   filePath?: string;
+  slides?: boolean;
+  validatorOptions?: Record<string, unknown>;
   literateJavaOutputPaths?: Set<string>;
   sourceUrlPath?: string;
   validTargets?: Set<string>;
@@ -58,13 +57,7 @@ export function createMarkdown(
   siteVariables: SiteVariables,
   options: CreateMarkdownOptions = {},
 ): MarkdownIt {
-  const {
-    validatorOptions = {},
-    filePath,
-    literateJavaOutputPaths,
-    sourceUrlPath,
-    validTargets,
-  } = options;
+  const { filePath, slides = false } = options;
   const markdown = new MarkdownIt({ html: true, typographer: true })
     .use(headingSubtitlePlugin)
     .use(markdownItAnchor, { tabIndex: false })
@@ -72,12 +65,6 @@ export function createMarkdown(
     .use(markdownItDeflist)
     .use(deflistIdPlugin)
     .use(externalLinksPlugin, siteVariables)
-    .use(validateInternalLinksPlugin, validatorOptions)
-    .use(applyBasePathPlugin, siteVariables, {
-      literateJavaOutputPaths,
-      sourceUrlPath,
-      validTargets,
-    })
     .use(tocPlugin)
     .use(columnsPlugin)
     .use(markdownItKatex)
@@ -115,6 +102,232 @@ export function createMarkdown(
       },
     });
 
+  function createWrapperToken(
+    type: string,
+    nesting: -1 | 0 | 1,
+    attributes: [string, string][],
+  ): Token {
+    const token = new Token(type, 'div', nesting);
+    token.attrs = attributes;
+    return token;
+  }
+
+  function isInlineOnlyTokenStream(tokens: Token[]): boolean {
+    return (
+      tokens.length === 1 &&
+      tokens[0]?.type === 'inline' &&
+      tokens[0].level === 0
+    );
+  }
+
+  function findTagEnd(html: string, start: number): number {
+    let quote: '"' | "'" | null = null;
+
+    for (let i = start + 1; i < html.length; i++) {
+      const char = html[i];
+      if (quote) {
+        if (char === quote) {
+          quote = null;
+        }
+        continue;
+      }
+
+      if (char === '"' || char === "'") {
+        quote = char;
+        continue;
+      }
+
+      if (char === '>') {
+        return i;
+      }
+    }
+
+    return -1;
+  }
+
+  function stripActualHrTags(html: string): string {
+    const rawTextTags = new Set(['script', 'style', 'title', 'textarea']);
+    const lowerHtml = html.toLowerCase();
+    let result = '';
+    let index = 0;
+    let rawTextTag: string | null = null;
+
+    while (index < html.length) {
+      if (rawTextTag) {
+        const closeStart = lowerHtml.indexOf(`</${rawTextTag}`, index);
+        if (closeStart === -1) {
+          result += html.slice(index);
+          break;
+        }
+
+        result += html.slice(index, closeStart);
+        const closeEnd = findTagEnd(html, closeStart);
+        if (closeEnd === -1) {
+          result += html.slice(closeStart);
+          break;
+        }
+
+        result += html.slice(closeStart, closeEnd + 1);
+        index = closeEnd + 1;
+        rawTextTag = null;
+        continue;
+      }
+
+      const openStart = html.indexOf('<', index);
+      if (openStart === -1) {
+        result += html.slice(index);
+        break;
+      }
+
+      result += html.slice(index, openStart);
+
+      if (html.startsWith('<!--', openStart)) {
+        const commentEnd = html.indexOf('-->', openStart + 4);
+        if (commentEnd === -1) {
+          result += html.slice(openStart);
+          break;
+        }
+
+        result += html.slice(openStart, commentEnd + 3);
+        index = commentEnd + 3;
+        continue;
+      }
+
+      let tagStart = openStart + 1;
+      let isClosingTag = false;
+      if (html[tagStart] === '/') {
+        isClosingTag = true;
+        tagStart++;
+      }
+
+      if (!/[A-Za-z]/.test(html[tagStart] ?? '')) {
+        result += '<';
+        index = openStart + 1;
+        continue;
+      }
+
+      let nameEnd = tagStart;
+      while (/[A-Za-z0-9:-]/.test(html[nameEnd] ?? '')) {
+        nameEnd++;
+      }
+
+      const tagName = html.slice(tagStart, nameEnd).toLowerCase();
+      const tagEnd = findTagEnd(html, openStart);
+      if (tagEnd === -1) {
+        result += html.slice(openStart);
+        break;
+      }
+
+      const tagText = html.slice(openStart, tagEnd + 1);
+      const tagBody = html.slice(openStart + 1, tagEnd);
+      const isSelfClosing = /\/\s*$/.test(tagBody);
+
+      if (tagName === 'hr' && !isClosingTag) {
+        index = tagEnd + 1;
+        continue;
+      }
+
+      result += tagText;
+      index = tagEnd + 1;
+
+      if (!isClosingTag && !isSelfClosing && rawTextTags.has(tagName)) {
+        rawTextTag = tagName;
+      }
+    }
+
+    return result;
+  }
+
+  function sanitizeTokenForSlides(token: Token): Token | null {
+    if (token.type === 'inline') {
+      token.content = stripActualHrTags(token.content);
+      if (token.children) {
+        const sanitizedChildren: Token[] = [];
+        for (const child of token.children) {
+          const sanitizedChild = sanitizeTokenForSlides(child);
+          if (sanitizedChild) {
+            sanitizedChildren.push(sanitizedChild);
+          }
+        }
+        token.children = sanitizedChildren;
+      }
+      return token;
+    }
+
+    if (token.type !== 'html_block' && token.type !== 'html_inline') {
+      return token;
+    }
+
+    const strippedContent = stripActualHrTags(token.content);
+    if (strippedContent.trim() === '') {
+      return null;
+    }
+
+    token.content = strippedContent;
+    return token;
+  }
+
+  markdown.core.ruler.before('toc_collector', 'slides_transform', state => {
+    if (!slides) {
+      return;
+    }
+
+    if (isInlineOnlyTokenStream(state.tokens)) {
+      return;
+    }
+
+    const env = (state.env ??= {}) as Record<string, unknown>;
+    const slideGroups: Token[][] = [];
+    let currentSlide: Token[] = [];
+
+    for (const token of state.tokens) {
+      const sanitizedToken = sanitizeTokenForSlides(token);
+      if (!sanitizedToken) {
+        continue;
+      }
+
+      if (sanitizedToken.type === 'hr') {
+        if (sanitizedToken.level === 0) {
+          if (currentSlide.length > 0) {
+            slideGroups.push(currentSlide);
+            currentSlide = [];
+          }
+        }
+        continue;
+      }
+
+      currentSlide.push(sanitizedToken);
+    }
+
+    if (currentSlide.length > 0) {
+      slideGroups.push(currentSlide);
+    }
+
+    const transformedTokens = [
+      createWrapperToken('slide_deck_open', 1, [
+        ['class', 'slide-deck'],
+        ['data-slides-root', ''],
+      ]),
+    ];
+
+    for (const [slideIndex, slideTokens] of slideGroups.entries()) {
+      transformedTokens.push(
+        createWrapperToken('slide_open', 1, [
+          ['class', 'slide'],
+          ['data-slide-index', String(slideIndex)],
+        ]),
+      );
+      transformedTokens.push(...slideTokens);
+      transformedTokens.push(createWrapperToken('slide_close', -1, []));
+    }
+
+    transformedTokens.push(createWrapperToken('slide_deck_close', -1, []));
+
+    env.slides = true;
+    env.slideCount = slideGroups.length;
+    state.tokens = transformedTokens;
+  });
+
   // 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.
@@ -351,6 +564,13 @@ export function createMarkdown(
 
   markdown.renderer.rules.hidden_fence = () => '';
 
+  markdown.renderer.rules.slide_deck_open = () =>
+    '<div class="slide-deck" data-slides-root>';
+  markdown.renderer.rules.slide_deck_close = () => '</div>';
+  markdown.renderer.rules.slide_open = (tokens, idx) =>
+    `<div class="slide" data-slide-index="${tokens[idx].attrGet('data-slide-index') ?? ''}">`;
+  markdown.renderer.rules.slide_close = () => '</div>';
+
   markdown.renderer.rules.fence = (tokens, idx) => {
     const token = tokens[idx];
     const lang = token.info.trim().split(/\s+/)[0] || 'text';

package/build/utils/paths.ts

@@ -1,4 +1,5 @@
 import path from 'path';
+import { globals } from '../globals';
 import type { SiteVariables } from '../types';
 
 export function getPackageDir(): string {
@@ -6,7 +7,7 @@ export function getPackageDir(): string {
 }
 
 export function getProjectDir(): string {
-  return process.cwd();
+  return globals.cwd();
 }
 
 export function getContentDir(): string {