comark-footnotes 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+Copyright (c) 2026 onmax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The block and inline rules in src/index.ts are ported from markdown-it-footnote,
+https://github.com/markdown-it/markdown-it-footnote, under its license:
+
+Copyright (c) 2014-2015 Vitaly Puzrin, Alex Kocharin.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# comark-footnotes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://comark-ui.onmax.me/badge.svg?source=npm-version&package=comark-footnotes&icon=npm)](https://npmx.dev/package/comark-footnotes)
+[![npm downloads](https://comark-ui.onmax.me/badge.svg?source=npm-downloads&package=comark-footnotes&period=month&icon=npm)](https://npmx.dev/package/comark-footnotes)
+[![license](https://comark-ui.onmax.me/badge.svg?label=license&value=MIT)](https://npmx.dev/package/comark-footnotes)
+[![docs](https://comark-ui.onmax.me/badge.svg?label=docs&value=comark-ui.onmax.me)](https://comark-ui.onmax.me/footnotes/)
+
+Footnotes in [Comark](https://comark.dev), in place of `comark/plugins/footnotes`: `[^1]` references, `[^1]:` definitions that hold any Markdown over several lines and blocks, and `^[inline notes]`. A parse plugin with no components, so it works in any renderer.
+
+```sh
+pnpm add comark comark-footnotes
+```
+
+```ts
+import { parseMarkdown } from "comark";
+import footnotes from "comark-footnotes";
+
+const document = await parseMarkdown(markdown, {
+  plugins: [footnotes()],
+});
+```
+
+```md
+The deploy waits when the roof holds more than 12 pigeons[^count], unless it's a hotfix^[Two approvals.].
+
+[^count]: Counted once, from the window,
+    at 9:00.
+
+    Pigeons that fly off mid-count still count.
+```
+
+Notes are numbered in the order they're first referenced and listed in a section at the end. It is named `footnotes`, like Comark's plugin, and takes the same options (`label`, `hr`, `backRef`) and writes the same nodes, so it replaces it. When a plugin list holds both, Comark keeps the first.
+
+Compared with Comark's plugin, a definition inside fenced code stays in the code, Markdown in a note renders, and a note can run over several lines and blocks. A reference used twice gets its own id, `fnref-label-2`.
+
+## Issues
+
+A reference with no definition stays as text, and a definition nothing references is dropped. Each adds a sentence to `meta.issues`:
+
+```txt
+footnotes: [^gone] has no definition; add a "[^gone]: …" line, or remove the reference.
+footnotes: [^spare]: is never referenced; add [^spare] where it applies, or remove the definition.
+```
+
+## Credits
+
+The parser is ported from [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote) by Vitaly Puzrin and Alex Kocharin, MIT.

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+//#region src/index.d.ts
+export type FootnotesMeta = {
+  /** One readable sentence per problem with a footnote. Empty when the document has none. Other plugins add theirs too. */
+  issues: string[];
+  /** The comark-linter rule of each issue, by its sentence, so the linter reports it under its own code. */
+  issueRules: Record<string, string>;
+};
+export interface FootnotesOptions {
+  /** The section's heading. Default `"Footnotes"`; an empty string leaves the heading out. */
+  label?: string;
+  /** Whether a horizontal rule comes before the section. Default `true`. */
+  hr?: boolean;
+  /** The link from a note back to its reference. Default `"↩"`. */
+  backRef?: string;
+}
+/**
+ * Footnotes: `[^label]` references with `[^label]: …` definitions, which can run over indented lines and hold any
+ * blocks, and `^[inline notes]`. They're numbered in the order they're first referenced and listed at the end.
+ * It is named `footnotes`, so it takes the place of `comark/plugins/footnotes`, with the same nodes.
+ */
+declare const _default: import("comark").ComarkPluginFactory<FootnotesOptions, FootnotesMeta, {}>;
+//#endregion
+export { _default as default };

package/dist/index.mjs

@@ -0,0 +1,306 @@
+import { defineComarkPlugin } from "comark";
+//#region ../../shared/markdown-it.ts
+/**
+* An inline element and a block element, by the prefix of their `_open` and `_close` types. Not `mdc_block_slot` for
+* blocks: directly inside a `::component` Comark reads those as named slots and splits the block apart.
+*/
+const SPAN = "mdc_inline_span";
+const BLOCK = "blockquote";
+/**
+* Adds a rule before or after the first of `anchors` the parser has, else last. Comark's own rules exist only with
+* its default plugins, and markdown-exit throws on a missing anchor, which would make every parse throw.
+*/
+function addRule(ruler, place, anchors, name, fn, options) {
+	for (const anchor of anchors) try {
+		ruler[place](anchor, name, fn, options);
+		return;
+	} catch {}
+	ruler.push(name, fn, options);
+}
+//#endregion
+//#region src/index.ts
+const DEF = "cfn-def:";
+const REF = "cfn-ref:";
+const NOTE = "cfn-note";
+/** `[^label]: text`, with the lines indented under it, as a block that holds the definition's own blocks. */
+function definition(state, startLine, endLine, silent) {
+	const start = (state.bMarks[startLine] ?? 0) + (state.tShift[startLine] ?? 0);
+	const max = state.eMarks[startLine] ?? 0;
+	if (start + 4 > max) return false;
+	if (state.src.charCodeAt(start) !== 91 || state.src.charCodeAt(start + 1) !== 94) return false;
+	let pos = start + 2;
+	for (; pos < max; pos++) {
+		const ch = state.src.charCodeAt(pos);
+		if (ch === 32) return false;
+		if (ch === 93) break;
+	}
+	if (pos === start + 2) return false;
+	if (pos + 1 >= max || state.src.charCodeAt(++pos) !== 58) return false;
+	if (silent) return true;
+	pos++;
+	const label = state.src.slice(start + 2, pos - 2);
+	const open = state.push(`${BLOCK}_open`, DEF + label, 1);
+	open.map = [startLine, 0];
+	const saved = {
+		bMark: state.bMarks[startLine] ?? 0,
+		tShift: state.tShift[startLine] ?? 0,
+		sCount: state.sCount[startLine] ?? 0,
+		parentType: state.parentType
+	};
+	const afterColon = pos;
+	const initial = saved.sCount + pos - (saved.bMark + saved.tShift);
+	let offset = initial;
+	while (pos < max) {
+		const ch = state.src.charCodeAt(pos);
+		if (ch === 9) offset += 4 - offset % 4;
+		else if (ch === 32) offset++;
+		else break;
+		pos++;
+	}
+	state.tShift[startLine] = pos - afterColon;
+	state.sCount[startLine] = offset - initial;
+	state.bMarks[startLine] = afterColon;
+	state.blkIndent += 4;
+	state.parentType = "footnote";
+	if ((state.sCount[startLine] ?? 0) < state.blkIndent) state.sCount[startLine] = (state.sCount[startLine] ?? 0) + state.blkIndent;
+	state.md.block.tokenize(state, startLine, endLine);
+	state.parentType = saved.parentType;
+	state.blkIndent -= 4;
+	state.tShift[startLine] = saved.tShift;
+	state.sCount[startLine] = saved.sCount;
+	state.bMarks[startLine] = saved.bMark;
+	open.map[1] = state.line;
+	state.push(`${BLOCK}_close`, DEF + label, -1);
+	return true;
+}
+/** `[^label]`, as an empty span with the label. Whether a definition exists is decided in `post`, which reports it. */
+function reference(state, silent) {
+	const start = state.pos;
+	const max = state.posMax;
+	if (start + 3 > max) return false;
+	if (state.src.charCodeAt(start) !== 91 || state.src.charCodeAt(start + 1) !== 94) return false;
+	let pos = start + 2;
+	for (; pos < max; pos++) {
+		const ch = state.src.charCodeAt(pos);
+		if (ch === 32 || ch === 10) return false;
+		if (ch === 93) break;
+	}
+	if (pos === start + 2 || pos >= max) return false;
+	const end = skipIncomplete(state, pos + 1);
+	const next = state.src.charCodeAt(end);
+	if (end === pos + 1 && (next === 40 || next === 91)) return false;
+	if (!silent) {
+		const tag = REF + state.src.slice(start + 2, pos);
+		state.push(`${SPAN}_open`, tag, 1);
+		state.push(`${SPAN}_close`, tag, -1);
+	}
+	state.pos = end;
+	return true;
+}
+/** `^[text]`, a note written where it applies, as a span holding the note's inline content. */
+function inlineNote(state, silent) {
+	const start = state.pos;
+	const max = state.posMax;
+	if (start + 2 >= max) return false;
+	if (state.src.charCodeAt(start) !== 94 || state.src.charCodeAt(start + 1) !== 91) return false;
+	const end = state.md.helpers.parseLinkLabel(state, start + 1);
+	if (end < 0) return false;
+	if (!silent) {
+		state.push(`${SPAN}_open`, NOTE, 1);
+		state.pos = start + 2;
+		state.posMax = end;
+		state.md.inline.tokenize(state);
+		state.push(`${SPAN}_close`, NOTE, -1);
+	}
+	state.pos = skipIncomplete(state, end + 1);
+	state.posMax = max;
+	return true;
+}
+const INCOMPLETE = "(comark:incomplete-link)";
+const skipIncomplete = (state, pos) => state.src.startsWith(INCOMPLETE, pos) ? pos + 24 : pos;
+const markdownIt = (md) => {
+	addRule(md.block.ruler, "before", ["reference"], "footnote_def", definition, { alt: ["paragraph", "reference"] });
+	addRule(md.inline.ruler, "before", ["comark_inline_span", "link"], "footnote_inline", inlineNote);
+	addRule(md.inline.ruler, "before", ["comark_inline_span", "link"], "footnote_ref", reference);
+};
+const sanitizeLabel = (label) => label.replace(/[^a-zA-Z0-9_-]/g, (char) => `-${char.charCodeAt(0).toString(16)}-`);
+const isElement = (node) => Array.isArray(node) && node[0] !== null;
+/** The label after a marker's tag, or nothing for another element. */
+const labelAfter = (marker, [tag]) => tag.startsWith(marker) ? tag.slice(marker.length) : void 0;
+const childrenOf = ([, , ...children]) => children;
+const built = /* @__PURE__ */ new WeakMap();
+const pending = /* @__PURE__ */ new WeakMap();
+/** Takes every definition out of the tree, wherever it sits, keeping the first for each label and noting the repeats. */
+function takeDefinitions(nodes, start, found, repeated) {
+	for (let index = nodes.length - 1; index >= start; index--) {
+		const node = nodes[index];
+		if (!isElement(node)) continue;
+		const label = labelAfter(DEF, node);
+		if (label !== void 0) {
+			nodes.splice(index, 1);
+			const content = childrenOf(node);
+			takeDefinitions(content, 0, found, repeated);
+			if (found.has(label)) repeated.add(label);
+			found.set(label, content);
+			continue;
+		}
+		takeDefinitions(node, 2, found, repeated);
+	}
+}
+/**
+* Footnotes: `[^label]` references with `[^label]: …` definitions, which can run over indented lines and hold any
+* blocks, and `^[inline notes]`. They're numbered in the order they're first referenced and listed at the end.
+* It is named `footnotes`, so it takes the place of `comark/plugins/footnotes`, with the same nodes.
+*/
+var src_default = defineComarkPlugin((options) => {
+	const { label = "Footnotes", hr = true, backRef = "↩" } = options ?? {};
+	return {
+		name: "footnotes",
+		markdownItPlugins: [markdownIt],
+		post(state) {
+			const { tree } = state;
+			const issues = [];
+			const definitions = /* @__PURE__ */ new Map();
+			const repeated = /* @__PURE__ */ new Set();
+			takeDefinitions(tree.nodes, 0, definitions, repeated);
+			const notes = /* @__PURE__ */ new Map();
+			const missing = /* @__PURE__ */ new Set();
+			const ids = new Set([...definitions.keys()].map(sanitizeLabel));
+			let inline = 0;
+			const autoLabel = () => {
+				let next;
+				do
+					next = `note-${++inline}`;
+				while (definitions.has(next) || notes.has(next) || ids.has(sanitizeLabel(next)));
+				ids.add(sanitizeLabel(next));
+				return next;
+			};
+			const refTo = (key, content) => {
+				let note = notes.get(key);
+				if (!note) {
+					note = {
+						label: key,
+						id: sanitizeLabel(key),
+						content: content(),
+						refs: 0
+					};
+					notes.set(key, note);
+				}
+				const count = ++note.refs;
+				const sup = [
+					"sup",
+					{ class: "footnote-ref" },
+					[
+						"a",
+						{
+							href: `#fn-${note.id}`,
+							id: count === 1 ? `fnref-${note.id}` : `fnref-${note.id}-${count}`
+						},
+						`[${[...notes.keys()].indexOf(key) + 1}]`
+					]
+				];
+				built.set(sup, {
+					label: key,
+					content: note.content
+				});
+				return sup;
+			};
+			const replace = (nodes, start) => {
+				for (let index = start; index < nodes.length; index++) {
+					const node = nodes[index];
+					const waiting = pending.get(nodes)?.get(index);
+					if (waiting !== void 0 && node === `[^${waiting}]`) {
+						const content = definitions.get(waiting);
+						if (content) {
+							nodes[index] = refTo(waiting, () => content);
+							pending.get(nodes)?.delete(index);
+							continue;
+						}
+						missing.add(waiting);
+						continue;
+					}
+					if (!isElement(node)) continue;
+					const [tag] = node;
+					const key = labelAfter(REF, node);
+					const previous = tag === "sup" ? built.get(node) : void 0;
+					if (key !== void 0) {
+						const content = definitions.get(key);
+						if (content) nodes[index] = refTo(key, () => content);
+						else {
+							nodes[index] = `[^${key}]`;
+							let entries = pending.get(nodes);
+							if (!entries) pending.set(nodes, entries = /* @__PURE__ */ new Map());
+							entries.set(index, key);
+							missing.add(key);
+						}
+					} else if (tag === NOTE) {
+						const content = childrenOf(node);
+						nodes[index] = refTo(autoLabel(), () => content);
+					} else if (previous) nodes[index] = refTo(previous.label, () => previous.content);
+					if (nodes[index] !== node) continue;
+					replace(node, 2);
+				}
+			};
+			replace(tree.nodes, 0);
+			for (const note of notes.values()) replace(note.content, 0);
+			for (const key of missing) issues.push({
+				rule: "comark/footnotes/missing-definition",
+				message: `footnotes: [^${key}] has no definition; add a "[^${key}]: …" line, or remove the reference.`
+			});
+			for (const key of definitions.keys()) if (!notes.has(key)) issues.push({
+				rule: "comark/footnotes/unused-definition",
+				message: `footnotes: [^${key}]: is never referenced; add [^${key}] where it applies, or remove the definition.`
+			});
+			for (const key of repeated) issues.push({
+				rule: "comark/footnotes/duplicate-definition",
+				message: `footnotes: [^${key}]: is defined more than once, and only the first shows; give the others their own labels, or remove them.`
+			});
+			if (issues.length) {
+				tree.meta.issues = [...tree.meta.issues ?? [], ...issues.map((issue) => issue.message)];
+				tree.meta.issueRules = {
+					...tree.meta.issueRules,
+					...Object.fromEntries(issues.map((issue) => [issue.message, issue.rule]))
+				};
+			}
+			if (!notes.size) return;
+			const items = [...notes.values()].map((note) => {
+				const backrefs = Array.from({ length: note.refs }, (_, index) => [" ", [
+					"a",
+					{
+						href: index ? `#fnref-${note.id}-${index + 1}` : `#fnref-${note.id}`,
+						class: "footnote-backref"
+					},
+					backRef
+				]]).flat();
+				const content = [...note.content];
+				const last = content.at(-1);
+				if (isElement(last) && last[0] === "p") content[content.length - 1] = [...last, ...backrefs];
+				else content.push(...backrefs);
+				return [
+					"li",
+					{ id: `fn-${note.id}` },
+					...content
+				];
+			});
+			const rule = hr ? [["hr", {}]] : [];
+			const heading = label ? [[
+				"h2",
+				{ id: "footnotes" },
+				label
+			]] : [];
+			tree.nodes.push([
+				"section",
+				{ class: "footnotes" },
+				...rule,
+				...heading,
+				[
+					"ol",
+					{ class: "footnotes-list" },
+					...items
+				]
+			]);
+		}
+	};
+});
+//#endregion
+export { src_default as default };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "comark-footnotes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "Footnotes in Comark: [^1] references, [^1]: definitions over several lines and blocks, and ^[inline notes], in place of comark/plugins/footnotes.",
+  "keywords": [
+    "comark",
+    "endnotes",
+    "footnotes",
+    "markdown",
+    "mdc",
+    "plugin"
+  ],
+  "homepage": "https://comark-ui.onmax.me/footnotes",
+  "bugs": "https://github.com/onmax/comark-ui/issues",
+  "license": "MIT",
+  "author": "onmax",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onmax/comark-ui.git",
+    "directory": "packages/footnotes"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@comark/html": "^0.8.1",
+    "comark": "^0.8.1"
+  },
+  "peerDependencies": {
+    "comark": "^0.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "doctor": "vite-doctor . --no-cache --max-warnings 0 --format text"
+  }
 }