@abreen/tada 1.19.3 → 1.19.5

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,196 @@
+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;
+const LESS_THAN = 0x3c;
+const RAW_ANCHOR_OPEN = /^<a[\s>]/i;
+
+// 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;
+  }
+
+  // Whether a `<…>` construct (an autolink or inline HTML) renders an anchor.
+  // It is parsed alone with a throwaway `env`, and nothing in it can reach the
+  // superlink rule again.
+  function isAnchorMarkup(state: StateInline, markup: string): boolean {
+    const tokens: StateInline['tokens'] = [];
+    state.md.inline.parse(markup, state.md, {}, tokens);
+    return tokens.some(
+      token =>
+        token.type === 'link_open' ||
+        (token.type === 'html_inline' && RAW_ANCHOR_OPEN.test(token.content)),
+    );
+  }
+
+  // `parseLinkLabel` rejects bracketed links but not autolinks (`<https://…>`)
+  // or raw `<a>` tags. An anchor inside the superlink anchor is invalid HTML:
+  // the parser closes the outer one early, stranding the description.
+  //
+  // This walks the label the way `parseLinkLabel` does, with the silent
+  // `skipToken`, so the state's position cache keeps the work linear and rules
+  // that register things in `env`, such as inline footnotes, do not run.
+  function labelHasAnchor(
+    state: StateInline,
+    start: number,
+    end: number,
+  ): boolean {
+    const oldPos = state.pos;
+    let found = false;
+    state.pos = start;
+    while (state.pos < end && !found) {
+      const pos = state.pos;
+      state.md.inline.skipToken(state);
+      found =
+        state.src.charCodeAt(pos) === LESS_THAN &&
+        state.pos - pos > 1 &&
+        isAnchorMarkup(state, state.src.slice(pos, state.pos));
+    }
+    state.pos = oldPos;
+    return found;
+  }
+
+  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;
+    }
+
+    // Last, so labels are only scanned when everything else already matches
+    if (
+      labelHasAnchor(state, titleStart, titleEnd) ||
+      labelHasAnchor(state, descriptionStart, descriptionEnd)
+    ) {
+      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/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.3",
+  "version": "1.19.5",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "fontkit": "^2.0.4",
     "front-matter": "^4.0.2",
     "java-parser": "^3.0.1",
-    "katex": "^0.16.45",
+    "katex": "^0.18.2",
     "lodash": "^4.18.1",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
@@ -82,6 +82,9 @@
     "sharp": "^0.35.3",
     "shiki": "^4.0.2"
   },
+  "overrides": {
+    "katex": "^0.18.2"
+  },
   "lint-staged": {
     "*.{ts,js}": "prettier --write",
     "src/**/*.scss": [

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,25 +11,14 @@ 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;
 let currentPath = '';
 let applyingFragment = false;
-let fragmentTargetRequest = 0;
 
 const scrollByIndex = new Map<number, number>();
 const scrollByLocation = new Map<string, number>();
-// Stylesheets the navigator added that have not loaded or failed yet. Those in
-// the initial document have settled before the deferred client script runs.
-const pendingStylesheets = new Map<Element, Promise<void>>();
 
 type Direction = 'forward' | 'back';
 
@@ -78,19 +67,7 @@ function updateHead(document: Document, newDoc: Document): void {
 
   for (const link of newDoc.querySelectorAll('link[rel="stylesheet"]')) {
     if (!existingHrefs.has(link.getAttribute('href'))) {
-      const clone = link.cloneNode(true) as Element;
-      pendingStylesheets.set(
-        clone,
-        new Promise(resolve => {
-          const settle = () => {
-            pendingStylesheets.delete(clone);
-            resolve();
-          };
-          clone.addEventListener('load', settle, { once: true });
-          clone.addEventListener('error', settle, { once: true });
-        }),
-      );
-      document.head.appendChild(clone);
+      document.head.appendChild(link.cloneNode(true));
     }
   }
 }
@@ -266,53 +243,16 @@ export function isApplyingFragment(): boolean {
 // content loses it in every browser. A fragment navigation sets it in every
 // browser, but it can reset the entry's history state and scroll position, so
 // restore both.
-//
-// 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.
-//
-// 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, waited ? restoredTop : undefined);
-  };
-  apply();
-}
-
-function replaceFragmentTarget(window: Window, forcedTop?: number): void {
+export function applyFragmentTarget(window: Window): 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 } = window;
-  const scrollY = forcedTop ?? window.scrollY;
+  const { scrollX, scrollY } = window;
   applyingFragment = true;
   try {
     globals.replaceLocation(
@@ -324,41 +264,6 @@ function replaceFragmentTarget(window: Window, forcedTop?: number): 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(
@@ -472,12 +377,10 @@ export async function navigateToUrl(
     teardownPerPageComponents();
     swapContent(document, newDoc);
     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,
-        typeof scrollTarget === 'number' ? scrollTarget : undefined,
-      );
+      // Restore the entry's :target before updateHead adds stylesheets. WebKit
+      // defers fragment scrolling until they load, which would move the page
+      // away from the entry's restored scroll position.
+      applyFragmentTarget(window);
     }
     updateHead(document, newDoc);
     mountAppearancePickerForPage(window);