Lossless Changelog
fleet

LFM — The remark-citations Plugin and Its Spec

Hex-code footnote identifiers become sequentially-numbered citations at render time, so a citation can keep its stable ID while still displaying as [1], [2], [3] in reading order.

Michael StatonMusic Editor

Changelog - 2026-04-22 (#1)

LFM: remark-citations plugin and spec

Overview

Added remark-citations — a remark plugin that transforms hex-code (or numeric/mixed) footnote identifiers into sequentially-numbered citations with structured metadata parsing. Bundled into the @lossless-group/lfm preset as part of the standard pipeline.

Changes by Area

1. New Plugin: packages/lfm/src/plugins/remark-citations.ts

Runs after remark-gfm (which creates footnoteReference and footnoteDefinition MDAST nodes). The plugin:

  • Walks the tree depth-first, collecting footnote references in document order

  • Assigns sequential indices (1, 2, 3...) by order of first appearance

  • Parses structured definitions: [Title](URL), source domain, Published: / Updated: dates, year prefixes

  • Enriches footnoteReference nodes with data.citationIndex and data.citationHex

  • Removes footnoteDefinition nodes from the tree (rendered separately via consumer's Sources component)

  • Attaches tree.data.citations with ordered citation array and validation warnings

  • Supports source-ref attributes on directive nodes for image source attribution

  • Validates orphan references and unused definitions (build-time warnings)

2. LFM Preset Integration: packages/lfm/src/preset.ts

  • Added remarkCitations to the plugin chain, after remarkCallouts

  • New citations: boolean option in RemarkLfmOptions (default: true)

3. Exports: packages/lfm/src/index.ts

  • Exports remarkCitations plugin and types: Citation, CitationsData, CitationWarning, RemarkCitationsOptions

4. Build Config: packages/lfm/tsup.config.ts

  • Added plugins/remark-citations entry point

5. New Spec: context-v/specs/Remark-Citations-Plugin-for-Hex-Code-Footnote-Management.md

Full specification covering the problem, architecture, identifier modes, structured definition parsing, image directive integration, configuration, MDAST output contract, and test cases.

6. Updated Spec: context-v/specs/Codifying-a-Comprehensive-Extended-Markdown-Flavor-and-Shared-Package.md

Updated the main LFM spec to reference the citations plugin.

Files Changed Summary

New

  • packages/lfm/src/plugins/remark-citations.ts — Citation processing plugin

  • context-v/specs/Remark-Citations-Plugin-for-Hex-Code-Footnote-Management.md — Plugin specification

Modified

  • packages/lfm/src/index.ts — Added citations exports

  • packages/lfm/src/preset.ts — Wired citations into remarkLfm pipeline

  • packages/lfm/src/types/index.ts — Added citations option to RemarkLfmOptions

  • packages/lfm/tsup.config.ts — Added citations build entry

  • context-v/specs/Codifying-a-Comprehensive-Extended-Markdown-Flavor-and-Shared-Package.md — Updated LFM spec

  • pnpm-lock.yaml — Lockfile update for workspace resolution