Fixes to Markdown GFM footnotes

Author: webstackdev

src/content/articles/alert-fatigue-reduction-triage-actionable-alerts/index.mdx

@@ -29,7 +29,7 @@ The most visible symptom of alert fatigue is MTTA drift—mean time to acknowled
 
 There's solid research on this from healthcare, where alarm fatigue kills patients. Studies in ICUs found that 72-99% of alarms required no clinical intervention[^1], and staff developed coping mechanisms—turning down volume, disabling non-critical alarms, or simply not rushing to respond. Software operations is no different.
 
-[^1]: Sendelbach S, Funk M. "Alarm fatigue: a patient safety concern." AACN Adv Crit Care. 2013 Oct-Dec;24(4):378-86.
+[^1]: Sendelbach S, Funk M. "Alarm fatigue: a patient safety concern." AACN Adv Crit Care. 2013 Oct-Dec: 378-86.
 
 The feedback loop makes it worse. After an incident caused by a missed alert, the instinct is to add more alerts. But if the alert was missed because of volume, adding more alerts makes the next miss more likely, not less. You can't fix what you haven't measured—and most teams have never actually measured their alert usefulness.
 

src/lib/markdown/__tests__/integration/rehype-footnotes-title-astro.spec.ts

@@ -19,4 +19,22 @@ describe('rehype-footnotes-title (Layer 2: With Astro Pipeline)', () => {
     expect(html).toContain('data-footnote-backref')
     expect(html).toContain('title="Return to footnote 1"')
   })
+
+  it('should set aria-labelledby on the footnotes section', async () => {
+    const markdown = `Here is a footnote.[^1]
+
+[^1]: My reference.`
+
+    const html = await processWithAstroSettings({
+      markdown,
+      plugin: rehypeFootnotesTitle,
+      pluginOptions: rehypeFootnotesTitleConfig,
+      stage: 'rehype',
+    })
+
+    expect(html).toContain('data-footnotes')
+    expect(html).toContain('aria-labelledby="footnote-label"')
+    expect(html).toContain('id="footnote-label"')
+    expect(html).not.toContain('class="sr-only"')
+  })
 })

src/lib/markdown/__tests__/integration/remark-restore-time-colons-astro.spec.ts

@@ -11,4 +11,18 @@ describe('remark-restore-time-colons (Layer 2: With Astro Pipeline)', () => {
     expect(html).toContain('12:00:01')
     expect(html).not.toContain('<div></div>')
   })
+
+  it('preserves citation page ranges inside footnotes', async () => {
+    const markdown = [
+      'Alarm fatigue reference[^1].',
+      '',
+      '[^1]: Sendelbach S, Funk M. "Alarm fatigue: a patient safety concern." AACN Adv Crit Care. 2013 Oct-Dec;24(4):378-86.',
+    ].join('\n')
+
+    const html = await processWithFullPipeline(markdown)
+
+    expect(html).toContain('24(4):378-86')
+    expect(html).not.toContain('<div></div>')
+    expect(html).not.toContain('</p><div></div>')
+  })
 })

src/lib/markdown/plugins/rehype-footnotes-title/__tests__/index.spec.ts

@@ -37,4 +37,23 @@ describe('rehype-footnotes-title (Layer 1: Isolated)', () => {
     expect(html).toContain('data-footnote-ref')
     expect(html).not.toContain('data-footnote-ref" title=')
   })
+
+  it('should link footnotes section to its Footnotes heading with aria-labelledby', async () => {
+    const markdown = `Here is a footnote.[^1]
+
+[^1]: My reference.`
+
+    const html = await processIsolated({
+      markdown,
+      stage: 'rehype',
+      plugin: rehypeFootnotesTitle,
+      pluginOptions: rehypeFootnotesTitleConfig,
+      gfm: true,
+    })
+
+    expect(html).toContain('data-footnotes')
+    expect(html).toContain('aria-labelledby="footnote-label"')
+    expect(html).toContain('id="footnote-label"')
+    expect(html).not.toContain('class="sr-only"')
+  })
 })

src/lib/markdown/plugins/rehype-footnotes-title/index.ts

@@ -1,5 +1,69 @@
 import { visit } from 'unist-util-visit'
-import type { Root, Element } from 'hast'
+import type { Root, Element, ElementContent, Text } from 'hast'
+
+const FOOTNOTES_HEADING_TEXT = 'Footnotes'
+const FOOTNOTES_HEADING_ID = 'footnote-label'
+
+function isElementNode(node: ElementContent): node is Element {
+  return node.type === 'element'
+}
+
+function getNodeText(node: Element): string {
+  let textContent = ''
+
+  for (const child of node.children) {
+    if (child.type === 'text') {
+      textContent += (child as Text).value
+      continue
+    }
+
+    if (isElementNode(child)) {
+      textContent += getNodeText(child)
+    }
+  }
+
+  return textContent
+}
+
+function findFootnotesHeading(section: Element): Element | null {
+  for (const child of section.children) {
+    if (!isElementNode(child) || child.tagName !== 'h2') continue
+
+    if (getNodeText(child).trim() === FOOTNOTES_HEADING_TEXT) {
+      return child
+    }
+  }
+
+  return null
+}
+
+function labelFootnotesSection(section: Element): void {
+  const heading = findFootnotesHeading(section)
+  if (!heading) return
+
+  const headingProperties = heading.properties || {}
+
+  const headingClasses = headingProperties['className']
+  if (Array.isArray(headingClasses)) {
+    headingProperties['className'] = headingClasses.filter(className => className !== 'sr-only')
+  }
+
+  const headingId = typeof headingProperties['id'] === 'string'
+    ? headingProperties['id']
+    : FOOTNOTES_HEADING_ID
+
+  headingProperties['id'] = headingId
+  heading.properties = headingProperties
+
+  const sectionProperties = section.properties || {}
+  sectionProperties['aria-labelledby'] = headingId
+  section.properties = sectionProperties
+}
+
+function isFootnotesSection(node: Element): boolean {
+  const properties = node.properties || {}
+  return 'dataFootnotes' in properties || 'data-footnotes' in properties
+}
 
 function getIdentifierFromBackrefHref(href: unknown): string | null {
   if (typeof href !== 'string') return null
@@ -27,6 +91,10 @@ export type RehypeFootnotesTitleOptions = string
 export function rehypeFootnotesTitle(titleTemplate: RehypeFootnotesTitleOptions = '') {
   return (tree: Root) => {
     visit(tree, 'element', (node: Element) => {
+      if (node.tagName === 'section' && isFootnotesSection(node)) {
+        labelFootnotesSection(node)
+      }
+
       if (node.tagName !== 'a') return
 
       const properties = node.properties || {}

src/lib/markdown/plugins/rehype-tailwind/index.ts

@@ -198,10 +198,11 @@ export function rehypeTailwindClasses() {
        */
       if (['h2', 'h3', 'h4'].includes(node.tagName)) {
         node.properties = node.properties || {}
+        const headingTextClass = 'text-page-inverse'
         node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
           'relative',
           'my-6',
-          'text-page-inverse',
+          headingTextClass,
           /**
            * Remove top margin from first child element of headings since we're
            * controlling bottom margin here.

src/lib/markdown/plugins/remark-restore-time-colons/__tests__/index.spec.ts

@@ -110,6 +110,24 @@ describe('remark-restore-time-colons', () => {
     })
   })
 
+  describe('citation page ranges', () => {
+    it('corrupts citation page ranges without the fix', async () => {
+      const output = await processWithoutFix(
+        'AACN Adv Crit Care. 2013 Oct-Dec;24(4):378-86.'
+      )
+      expect(output).toContain('<div></div>')
+      expect(output).not.toContain('24(4):378-86')
+    })
+
+    it('preserves citation page ranges with the fix', async () => {
+      const output = await processToHtml(
+        'AACN Adv Crit Care. 2013 Oct-Dec;24(4):378-86.'
+      )
+      expect(output).toContain('24(4):378-86')
+      expect(output).not.toContain('<div></div>')
+    })
+  })
+
   describe('non-time directives are unaffected', () => {
     it('does not interfere with alphabetic text directives', async () => {
       // A real text directive like :abbr[HTML] should not be touched

src/lib/markdown/plugins/remark-restore-time-colons/index.ts

@@ -17,11 +17,19 @@ import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 
 /**
- * Test whether a directive name is purely numeric (0-9).
- * No valid remark directive would use a numeric-only name, so these are
- * always false positives created from time-like strings.
+ * Test whether a directive name is numeric-like and therefore a likely
+ * false positive from prose (time/citation/page-range text).
+ *
+ * Examples we want to restore:
+ * - :47            (time)
+ * - :59            (time)
+ * - :378-86        (citation page range)
+ * - :378–86 / :378—86 (en/em dash variants)
+ *
+ * We intentionally avoid alphabetic names so real directives such as
+ * `:abbr[...]` remain untouched.
  */
-const isNumericName = (name: string): boolean => /^\d+$/.test(name)
+const isNumericLikeName = (name: string): boolean => /^\d[\d\-–—]*$/.test(name)
 
 /** Record of a directive node to restore, collected during walk. */
 interface PendingRestore {
@@ -43,8 +51,8 @@ const remarkRestoreTimeColons: Plugin<[], Root> = () => {
         return
       }
 
-      // Only restore purely-numeric names; real directives have alphabetic names
-      if (!isNumericName(node.name)) return
+      // Restore numeric-like names; real directives have alphabetic names
+      if (!isNumericLikeName(node.name)) return
       if (index === undefined || !parent) return
 
       pending.push({ parent: parent as Parent, index, name: node.name })

src/styles/markdown.css

@@ -12,6 +12,59 @@
   text-decoration: none;
 }
 
+/**
+ * Footnote backref icon link should not inherit dotted underline decoration.
+ */
+.markdown-content__prose a[data-footnote-backref],
+.markdown-content__prose a[data-footnote-backref]:hover,
+.markdown-content__prose a.footnote-backref,
+.markdown-content__prose a.footnote-backref:hover {
+  text-decoration: none;
+}
+
+.markdown-content__prose a[data-footnote-backref],
+.markdown-content__prose a.footnote-backref {
+  display: inline-block;
+  transition: color 150ms ease, transform 150ms ease;
+}
+
+.markdown-content__prose a[data-footnote-backref]:hover,
+.markdown-content__prose a[data-footnote-backref]:focus-visible,
+.markdown-content__prose a.footnote-backref:hover,
+.markdown-content__prose a.footnote-backref:focus-visible {
+  color: var(--color-content-offset);
+  transform: translateY(-2px);
+}
+
+/**
+ * Add a separator above the generated footnotes section.
+ */
+.markdown-content__prose section[data-footnotes] {
+  border-top: 1px solid var(--color-trim);
+  margin-top: 2rem;
+  padding-top: 1rem;
+}
+
+/**
+ * Footnote list marker numbers should fit comfortably inside the circular marker.
+ */
+.markdown-content__prose section[data-footnotes] .markdown-list ol {
+  margin-left: 4px;
+}
+
+.markdown-content__prose section[data-footnotes] .markdown-list ol > li {
+  padding-left: calc(1.32em + 0.375rem);
+}
+
+.markdown-content__prose section[data-footnotes] .markdown-list ol > li::before {
+  background-color: var(--color-content-active);
+  font-size: 0.8em;
+  line-height: 1em;
+  height: 1.32em;
+  top: calc(0.15em + 2px);
+  width: 1.32em;
+}
+
 /**
  * Details and Summary stylings. Gives a thin line with a "+" symbol,
  * and animates the content when opening and closing.