@abreen/tada 1.19.3 → 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/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.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;