@abreen/tada 1.19.2 → 1.19.4

package/README.md

@@ -68,6 +68,7 @@ A static site generator. The successor to Presto.
   * `??? question ... ???` renders a Q&A section; answer is hidden until click
     - To display clickable multiple choice options, use a [task list][task-list]
   * `+++ ... +++ ... +++` renders a two-column layout
+  * `[Title][Description](url)` renders a two-line superlink
   * Special heading subtitles with `## Heading # A subtitle here`
   * `{{{ _partial.md }}}` syntax for including partials
 

package/build/external-links-plugin.ts

@@ -5,16 +5,23 @@ import type { SiteVariables } from './types';
 
 const log = makeLogger(import.meta.url);
 
+export function isExternalHref(
+  href: string,
+  siteVariables: SiteVariables,
+): boolean {
+  if (!href.match(/^https?:\/\/.*$/)) {
+    return false;
+  }
+  const url = new URL(href);
+  return !siteVariables.internalDomains?.includes(url.host);
+}
+
 export default function externalLinks(
   md: MarkdownIt,
   siteVariables: SiteVariables,
 ): void {
   function isExternal(href: string): boolean {
-    if (!href.match(/^https?:\/\/.*$/)) {
-      return false;
-    }
-    const url = new URL(href);
-    return !siteVariables.internalDomains?.includes(url.host);
+    return isExternalHref(href, siteVariables);
   }
 
   function findMatchingClose(children: Token[], openIdx: number): number {

package/build/superlink-plugin.ts

@@ -0,0 +1,146 @@
+import type MarkdownIt from 'markdown-it';
+import type StateInline from 'markdown-it/lib/rules_inline/state_inline.mjs';
+import { isExternalHref } from './external-links-plugin';
+import type { SiteVariables } from './types';
+
+const OPEN_BRACKET = 0x5b;
+const CARET = 0x5e;
+const OPEN_PAREN = 0x28;
+const CLOSE_PAREN = 0x29;
+const NEWLINE = 0x0a;
+
+// Renders `[Title][Description](/destination.html)` as a two-line superlink.
+// It must run before the built-in `link` rule, which would otherwise
+// treat `[Title][Description]` as a reference link.
+export default function superlinkPlugin(
+  md: MarkdownIt,
+  siteVariables: SiteVariables,
+): void {
+  function skipSpaces(src: string, pos: number, max: number): number {
+    while (pos < max) {
+      const code = src.charCodeAt(pos);
+      if (!md.utils.isSpace(code) && code !== NEWLINE) {
+        break;
+      }
+      pos++;
+    }
+    return pos;
+  }
+
+  function pushPart(
+    state: StateInline,
+    name: 'title' | 'description',
+    start: number,
+    end: number,
+  ): void {
+    const open = state.push(`superlink_${name}_open`, 'span', 1);
+    open.attrs = [['class', `superlink-${name}`]];
+
+    const oldPos = state.pos;
+    const oldMax = state.posMax;
+    state.pos = start;
+    state.posMax = end;
+    state.md.inline.tokenize(state);
+    state.pos = oldPos;
+    state.posMax = oldMax;
+
+    state.push(`superlink_${name}_close`, 'span', -1);
+  }
+
+  function superlinkRule(state: StateInline, silent: boolean): boolean {
+    const src = state.src;
+    const max = state.posMax;
+
+    if (src.charCodeAt(state.pos) !== OPEN_BRACKET) {
+      return false;
+    }
+
+    // Leave a footnote reference such as `[^1][source](url)` to the footnote
+    // plugin, whose rule would otherwise never see it.
+    if (src.charCodeAt(state.pos + 1) === CARET) {
+      return false;
+    }
+
+    const titleStart = state.pos + 1;
+    const titleEnd = state.md.helpers.parseLinkLabel(state, state.pos, true);
+    if (titleEnd < 0) {
+      return false;
+    }
+
+    // The description label must follow the title label immediately.
+    const descriptionOpen = titleEnd + 1;
+    if (
+      descriptionOpen >= max ||
+      src.charCodeAt(descriptionOpen) !== OPEN_BRACKET
+    ) {
+      return false;
+    }
+    const descriptionStart = descriptionOpen + 1;
+    const descriptionEnd = state.md.helpers.parseLinkLabel(
+      state,
+      descriptionOpen,
+      true,
+    );
+    if (descriptionEnd < 0) {
+      return false;
+    }
+
+    if (
+      src.slice(titleStart, titleEnd).trim() === '' ||
+      src.slice(descriptionStart, descriptionEnd).trim() === ''
+    ) {
+      return false;
+    }
+
+    let pos = descriptionEnd + 1;
+    if (pos >= max || src.charCodeAt(pos) !== OPEN_PAREN) {
+      return false;
+    }
+    pos = skipSpaces(src, pos + 1, max);
+    if (pos >= max) {
+      return false;
+    }
+
+    const destination = state.md.helpers.parseLinkDestination(src, pos, max);
+    if (!destination.ok) {
+      return false;
+    }
+    const href = state.md.normalizeLink(destination.str);
+    if (!state.md.validateLink(href)) {
+      return false;
+    }
+
+    pos = skipSpaces(src, destination.pos, max);
+    if (pos >= max || src.charCodeAt(pos) !== CLOSE_PAREN) {
+      return false;
+    }
+
+    if (!silent) {
+      const external = isExternalHref(href, siteVariables);
+      const open = state.push('superlink_open', 'a', 1);
+      open.attrs = [
+        ['href', href],
+        ['class', external ? 'button superlink external' : 'button superlink'],
+      ];
+      if (external) {
+        open.attrs.push(['target', '_blank'], ['rel', 'noopener noreferrer']);
+      }
+
+      pushPart(state, 'title', titleStart, titleEnd);
+
+      // The spans are blocks, so this collapses visually, but it keeps text
+      // extraction (search indexing, copy and paste) from gluing the last word
+      // of the title to the first word of the description.
+      state.push('text', '', 0).content = '\n';
+
+      pushPart(state, 'description', descriptionStart, descriptionEnd);
+
+      state.push('superlink_close', 'a', -1);
+    }
+
+    state.pos = pos + 1;
+    return true;
+  }
+
+  md.inline.ruler.before('link', 'superlink', superlinkRule);
+}

package/build/utils/markdown.ts

@@ -12,6 +12,7 @@ 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 superlinkPlugin from '../superlink-plugin';
 import { tocPlugin } from '../toc-plugin';
 import columnsPlugin from '../columns-plugin';
 import katexPlugin from './katex';
@@ -61,6 +62,7 @@ export function createMarkdown(
     .use(markdownItDeflist)
     .use(deflistIdPlugin)
     .use(externalLinksPlugin, siteVariables)
+    .use(superlinkPlugin, siteVariables)
     .use(tocPlugin)
     .use(columnsPlugin)
     .use(katexPlugin)

package/build/watch/engine.ts

@@ -22,6 +22,10 @@ export function runWatchEngine<Meta>(
   const debounceMs = options.debounceMs ?? 300;
   const watchers: ReturnType<typeof chokidar.watch>[] = [];
   const pending = new Set<string>();
+  const removed = new Map<
+    string,
+    { watcher: ReturnType<typeof chokidar.watch>; root: string }
+  >();
   let uncommitted = new Set<string>();
   let closed = false;
   let fatal: { error: unknown } | undefined;
@@ -33,6 +37,7 @@ export function runWatchEngine<Meta>(
   function stop(): void {
     closed = true;
     pending.clear();
+    removed.clear();
     if (timer !== undefined) {
       clock.clearTimeout(timer);
     }
@@ -78,6 +83,52 @@ export function runWatchEngine<Meta>(
     }
   }
 
+  function isFile(filePath: string): boolean {
+    try {
+      return dependencies.stat(filePath)?.isFile() ?? false;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOTDIR') {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  function isInside(root: string, filePath: string): boolean {
+    const relative = path.relative(root, filePath);
+    return (
+      relative !== '' &&
+      relative !== '..' &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative)
+    );
+  }
+
+  /**
+   * Chokidar tracks entries by name, so a directory replaced by a file keeps
+   * its directory subscription and edits to the file are never reported. When
+   * a poll misses the moment between the two, the only events are removals of
+   * what was inside the directory. Once changes have settled, resubscribe any
+   * parent of a removed path that is now a file.
+   */
+  function resubscribeReplacedDirectories(): void {
+    const checked = new Set<string>();
+    for (const [removedPath, { watcher, root }] of removed) {
+      for (
+        let dir = path.dirname(removedPath);
+        isInside(root, dir) && !checked.has(dir);
+        dir = path.dirname(dir)
+      ) {
+        checked.add(dir);
+        if (isFile(dir)) {
+          watcher.unwatch(dir);
+          watcher.add(dir);
+        }
+      }
+    }
+    removed.clear();
+  }
+
   async function emit(event: WatchLifecycleEvent<Meta>): Promise<void> {
     if (!closed) {
       await options.onEvent?.(event);
@@ -139,7 +190,13 @@ export function runWatchEngine<Meta>(
           fail(error);
         }
       };
-      watcher.on('add', included).on('unlink', included);
+      const removedPath = (filePath: string) => {
+        if (!closed) {
+          removed.set(filePath, { watcher, root: target.path });
+        }
+        included(filePath);
+      };
+      watcher.on('add', included).on('unlink', removedPath);
       watcher.on('change', (filePath, stats) => {
         if (closed) {
           return;
@@ -156,20 +213,18 @@ export function runWatchEngine<Meta>(
       });
       watcher.on('addDir', included);
       watcher.on('unlinkDir', filePath => {
-        included(filePath);
+        removedPath(filePath);
         // Wait until Chokidar finishes closing the old directory subscription.
         queueMicrotask(() => {
           if (closed) {
             return;
           }
           try {
-            if (dependencies.stat(filePath)?.isFile()) {
+            if (isFile(filePath)) {
               watcher.add(filePath);
             }
           } catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== 'ENOTDIR') {
-              fail(error);
-            }
+            fail(error);
           }
         });
       });
@@ -197,6 +252,7 @@ export function runWatchEngine<Meta>(
       while (!closed && pending.size) {
         const paths = new Set([...uncommitted, ...pending]);
         pending.clear();
+        resubscribeReplacedDirectories();
         const outcome = await build(paths);
         if (!outcome?.ok) {
           uncommitted = paths;

package/init/content/markdown.md

@@ -373,6 +373,27 @@ static boolean isOdd(int n) {
 ```
 +++
 
+### Superlinks
+
+Use
+
+```
+[Home][Back to the front page](index.html)
+[Markdown][You are here](markdown.html)
+[KaTeX][The library behind math support](https://katex.org/)
+```
+
+to create a link with a title and a description:
+
+[Home][Back to the front page](index.html)
+[Markdown][You are here](markdown.html)
+[KaTeX][The library behind math support](https://katex.org/)
+
+Superlinks are rendered as block elements, so don't use them inline, in the
+middle of a paragraph, or in a heading. Put them on their own lines, as above.
+A superlink to another website, like the last one above, opens in a new tab and
+shows an external link icon in place of the chevron.
+
 ---
 
 ## Additional features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.19.2",
+  "version": "1.19.4",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",

package/src/_alerts.scss

@@ -35,7 +35,7 @@
     background: inherit;
   }
 
-  a {
+  a:not(.superlink) {
     @include link-underline;
 
     color: var(--fg-color);

package/src/_content.scss

@@ -164,6 +164,60 @@ select:focus {
   border-color: var(--fg-color);
 }
 
+a.superlink {
+  position: relative;
+  display: block;
+  padding-block: calc(var(--gap) / 2);
+  padding-inline: var(--gap)
+    calc(var(--gap) * 2 + var(--icon-breadcrumb-separator-size));
+  font-size: inherit;
+  text-align: left;
+
+  + a.superlink {
+    margin-top: var(--gap);
+  }
+
+  .superlink-title {
+    display: block;
+    font-weight: 600;
+  }
+
+  .superlink-description {
+    display: block;
+    font-weight: normal;
+    color: var(--fg2-color);
+  }
+
+  &::after {
+    @include contained-mask(var(--icon-breadcrumb-separator));
+
+    position: absolute;
+    top: 50%;
+    right: var(--gap);
+    width: var(--icon-breadcrumb-separator-size);
+    height: var(--icon-breadcrumb-separator-size);
+    content: '';
+    background-color: var(--fg2-color);
+    transform: translateY(-50%);
+  }
+
+  // External superlinks get the external-link icon instead of the chevron from
+  // the shared `a.external` rules above, which win on mask, size and content.
+  // They also set currentcolor, so restore the subdued color. The icon's box
+  // is smaller than the chevron's, so shift it left to share the chevron's
+  // center, which keeps the two optically aligned.
+  &.external::after {
+    right: calc(
+      var(--gap) +
+        (
+          var(--icon-breadcrumb-separator-size) - var(--icon-external-link-size)
+        ) /
+        2
+    );
+    background-color: var(--fg2-color);
+  }
+}
+
 button.icon-button {
   display: inline-flex;
   align-items: center;

package/src/navigate/runtime.ts

@@ -11,6 +11,13 @@ import { swapHeaderTitle } from '../header';
 export const NAVIGATION_EVENT = 'tada:navigation';
 
 const LOADING_CURSOR_DELAY = 400;
+const HOLD_SCROLL_FRAMES = 6;
+const HOLD_SCROLL_RELEASE_EVENTS = [
+  'wheel',
+  'touchstart',
+  'keydown',
+  'pointerdown',
+] as const;
 
 let currentAbortController: AbortController | null = null;
 let historyIndex = 0;
@@ -263,33 +270,49 @@ export function isApplyingFragment(): boolean {
 // WebKit defers fragment scrolling until pending stylesheets load, which would
 // later move the page away from the restored scroll position. Wait for them
 // first, and skip the update if another request or navigation replaced it.
-export function applyFragmentTarget(window: Window): void {
+//
+// That deferred scroll can also set :target before the wait ends, which would
+// leave nothing to replace. WebKit then scrolls to the target again on the next
+// frame, undoing a scroll back to the saved position. A fragment navigation of
+// our own does not have that problem, so after waiting, repeat it even when
+// :target matches, restoring the saved position the caller passed in. When the
+// last stylesheet finishes loading just after the content swap, WebKit can
+// still scroll to the target in the next rendering update, after our restore,
+// so hold that position for a few frames.
+export function applyFragmentTarget(
+  window: Window,
+  restoredTop?: number,
+): void {
   const request = ++fragmentTargetRequest;
   const { href } = window.location;
+  let waited = false;
   const apply = (): void => {
     if (request !== fragmentTargetRequest || window.location.href !== href) {
       return;
     }
     const pending = Array.from(pendingStylesheets.values());
     if (pending.length > 0) {
+      waited = true;
       void Promise.all(pending).then(apply);
       return;
     }
-    replaceFragmentTarget(window);
+    replaceFragmentTarget(window, waited ? restoredTop : undefined);
   };
   apply();
 }
 
-function replaceFragmentTarget(window: Window): void {
+function replaceFragmentTarget(window: Window, forcedTop?: number): void {
   const { document, history, location } = window;
   if (
+    forcedTop === undefined &&
     document.querySelector(':target') === getHashTarget(document, location.hash)
   ) {
     return;
   }
   const { href } = location;
   const state = history.state;
-  const { scrollX, scrollY } = window;
+  const { scrollX } = window;
+  const scrollY = forcedTop ?? window.scrollY;
   applyingFragment = true;
   try {
     globals.replaceLocation(
@@ -301,6 +324,41 @@ function replaceFragmentTarget(window: Window): void {
   }
   history.replaceState(state, '', href);
   window.scrollTo({ left: scrollX, top: scrollY });
+  if (forcedTop !== undefined) {
+    holdScroll(window, scrollX, scrollY);
+  }
+}
+
+// Scroll back to the given position on each of the next few frames if the
+// browser moved the page, until the visitor scrolls or the URL changes
+function holdScroll(window: Window, left: number, top: number): void {
+  const { href } = window.location;
+  let held = true;
+  const release = (): void => {
+    held = false;
+    for (const type of HOLD_SCROLL_RELEASE_EVENTS) {
+      window.removeEventListener(type, release);
+    }
+  };
+  for (const type of HOLD_SCROLL_RELEASE_EVENTS) {
+    window.addEventListener(type, release, { passive: true });
+  }
+  let frames = 0;
+  const tick = (): void => {
+    if (!held || window.location.href !== href) {
+      release();
+      return;
+    }
+    if (Math.abs(window.scrollY - top) > 1) {
+      window.scrollTo({ left, top });
+    }
+    if (++frames < HOLD_SCROLL_FRAMES) {
+      window.requestAnimationFrame(tick);
+    } else {
+      release();
+    }
+  };
+  window.requestAnimationFrame(tick);
 }
 
 export async function navigateToUrl(
@@ -416,7 +474,10 @@ export async function navigateToUrl(
     if (!pushHistory) {
       // Restore the entry's :target before updateHead adds stylesheets, so it
       // applies right away unless an earlier stylesheet is still loading
-      applyFragmentTarget(window);
+      applyFragmentTarget(
+        window,
+        typeof scrollTarget === 'number' ? scrollTarget : undefined,
+      );
     }
     updateHead(document, newDoc);
     mountAppearancePickerForPage(window);

package/src/toc/_index.scss

@@ -149,10 +149,15 @@ body.code .toc ol a {
   width: var(--toc-alert-icon-size);
   height: var(--toc-alert-icon-size);
   margin-right: 4px;
-  vertical-align: sub;
+  vertical-align: middle;
   content: '';
 
   @include contained-mask(var(--toc-alert-icon));
+
+  // Center the icon on the cap height, which scales with each level's font
+  @supports (width: 1cap) {
+    vertical-align: calc(0.5cap - var(--toc-alert-icon-size) / 2);
+  }
 }
 
 .toc ol li.label {