@riebeckite/plugin-citations 0.0.14

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,79 @@
+# @riebeckite/plugin-citations
+
+[日本語版](./README_ja.md)
+
+Official Riebeckite plugin for BibTeX / BibLaTeX based citations in Markdown and Obsidian notes.
+
+```ts
+import { citations } from "@riebeckite/plugin-citations";
+
+export default {
+  plugins: [
+    citations({ bibliography: "references.bib" }),
+  ],
+};
+```
+
+## Supported citation syntax
+
+The plugin implements a stable Pandoc-inspired subset:
+
+- `[@smith2024]`
+- `[@smith2024; @doe2025]` — multiple keys must be separated by `;`
+- `@smith2024 argues that ...`
+- `[-@smith2024]` — suppress-author input
+- `[@smith2024, p. 42]` and `[see @doe2025]` — prefix and suffix are kept, rendering as `[1, p. 42]` and `[see 2]`
+
+Repeated citations reuse the first number assigned to that key. Under numeric labels, `[-@smith2024]` renders the same label as `[@smith2024]`.
+
+Inline `@key` must be preceded by the start of the text, whitespace, or `(`. Text attached directly to `@key` on the left — for example `本文@smith2024` — is not recognized; write `[@smith2024]` instead.
+
+Riebeckite parses `:name` as a directive before this plugin runs. When that split breaks a citation key, the plugin reassembles it, so `[@colon:2024]` and `@colon:2024 argues` both work. Keys may contain letters, digits, `-`, `_`, `:`, and `.`.
+
+Not transformed: inline code, fenced code blocks, HTML, frontmatter, normal Markdown links (at any nesting depth), and Obsidian WikiLinks.
+
+## Bibliography files
+
+- `citations({ bibliography })` paths are relative to the content root.
+- Frontmatter `bibliography` is resolved relative to the page first, then to the content root. Both `/` and `\` separators are accepted and `../` is normalized inside the string; every candidate still goes through the content source, so nothing outside the configured content root can be read.
+- The bibliography file is read at build time only. It is never copied into the output and absolute paths never appear in generated files.
+
+## Supported bibliography subset
+
+Curated entry types are `article`, `book`, `inproceedings`, and `misc`. Other entry types are still parsed and rendered with generic fields, and reported as `citation-unsupported-entry-type`.
+
+`@comment`, `@preamble`, and `@string` entries are accepted and skipped. Malformed entries report `citation-malformed-bibliography` and parsing resumes at the next `@`, so one broken entry does not discard the rest of the file.
+
+Supported syntax: multiline fields, quoted and braced values, nested braces, commas inside values, escaped characters, trailing commas, whitespace and CRLF.
+
+Reported through `citation-unsupported-bibliography-syntax` instead of failing silently:
+
+- `@string` macro references are rendered literally; they are not expanded.
+- `#` string concatenation keeps only the first part.
+
+## References section
+
+Pages with citations receive a `References` heading and an ordered list at the end of the Markdown body. Each entry carries an `id` of the form `ref-<sanitized key>`, where characters outside `[A-Za-z0-9_-]` are replaced by `-` and collisions get a deterministic numeric suffix. Citation labels link to that anchor.
+
+Use `referencesHeading` for localized headings:
+
+```ts
+citations({ bibliography: "references.bib", referencesHeading: "参考文献" })
+```
+
+## Diagnostics
+
+Reported through Riebeckite diagnostics:
+
+- `citation-unknown-key`
+- `citation-missing-bibliography`
+- `citation-malformed-bibliography`
+- `citation-duplicate-key`
+- `citation-unsupported-entry-type`
+- `citation-unsupported-bibliography-syntax`
+
+Citation numbering, reference ordering, generated HTML, and diagnostics are deterministic: identical input produces identical output.
+
+## License
+
+Apache-2.0

package/README_ja.md

@@ -0,0 +1,79 @@
+# @riebeckite/plugin-citations
+
+[English](./README.md)
+
+Markdown / Obsidian ノートで BibTeX / BibLaTeX の文献情報を使って引用を表示する、Riebeckite 公式プラグインです。
+
+```ts
+import { citations } from "@riebeckite/plugin-citations";
+
+export default {
+  plugins: [
+    citations({ bibliography: "references.bib" }),
+  ],
+};
+```
+
+## 対応する引用の記法
+
+Pandoc を参考にした、安定した一部の記法を扱います。
+
+- `[@smith2024]`
+- `[@smith2024; @doe2025]` — 複数のキーは `;` で区切る
+- `@smith2024 argues that ...`
+- `[-@smith2024]` — 著者名を出さない形の入力
+- `[@smith2024, p. 42]` と `[see @doe2025]` — prefix / suffix を保持し、`[1, p. 42]` と `[see 2]` として表示する
+
+同じ文献を何度も引用した場合は、最初に割り当てた番号を再利用します。番号形式の表示では `[-@smith2024]` と `[@smith2024]` のラベルは同じになります。
+
+本文中の `@key` は、テキストの先頭、空白、`(` のいずれかの直後に書きます。`本文@smith2024` のように `@key` の左が文字でつながっている形は認識されないため、`[@smith2024]` を使ってください。
+
+Riebeckite はこのプラグインより先に `:name` を directive として解釈します。directive 化によって引用キーが分断された場合はプラグインが組み直すため、`[@colon:2024]` と `@colon:2024 argues` の両方が動きます。キーに使えるのは英字、数字、`-`、`_`、`:`、`.` です。
+
+変換しない対象: inline code、fenced code block、HTML、frontmatter、任意の階層にある通常の Markdown リンク、Obsidian の WikiLink。
+
+## 文献ファイルの読み込み
+
+- `citations({ bibliography })` のパスはコンテンツルートからの相対パスです。
+- frontmatter の `bibliography` は、まずページからの相対パス、次にコンテンツルートからの相対パスとして解決します。`/` と `\` の両区切りを受け付け、`../` は文字列内で正規化します。候補はいずれも content source を通るため、設定されたコンテンツルートの外は読み込めません。
+- 文献ファイルはビルド時に読み込むだけで、出力にはコピーされず、絶対パスも生成物に現れません。
+
+## 対応する BibTeX の範囲
+
+重点的に扱う文献種別は `article`、`book`、`inproceedings`、`misc` です。その他の種別も汎用フィールドとして読み込んで表示し、`citation-unsupported-entry-type` として報告します。
+
+`@comment`、`@preamble`、`@string` は受け付けて読み飛ばします。壊れたエントリは `citation-malformed-bibliography` を出し、次の `@` から再開するため、1件の不正でファイル残りが消えることはありません。
+
+対応する構文: 複数行フィールド、引用符と波括弧の値、ネストした波括弧、値の中のカンマ、エスケープ文字、末尾カンマ、空白、CRLF。
+
+次は沈黙せず `citation-unsupported-bibliography-syntax` として報告します。
+
+- `@string` のマクロ参照は展開せずそのまま文字列として表示する
+- `#` による文字列連結は先頭の部分しか保持しない
+
+## 参考文献リスト
+
+引用があるページでは、Markdown 本文の末尾に `References` 見出しと番号付きリストを追加します。各項目には `ref-<正規化したキー>` 形式の `id` を付与します。`[A-Za-z0-9_-]` 以外の文字は `-` に置き換え、衝突した場合は決定的な連番を付けます。引用ラベルはこのアンカーへリンクします。
+
+日本語サイトでは見出しを変えられます。
+
+```ts
+citations({ bibliography: "references.bib", referencesHeading: "参考文献" })
+```
+
+## diagnostics
+
+以下を Riebeckite の diagnostics に出力します。
+
+- `citation-unknown-key`
+- `citation-missing-bibliography`
+- `citation-malformed-bibliography`
+- `citation-duplicate-key`
+- `citation-unsupported-entry-type`
+- `citation-unsupported-bibliography-syntax`
+
+引用番号、参考文献の並び、生成される HTML、diagnostics の順序は決定的で、同じ入力からは同じ出力になります。
+
+## ライセンス
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { CitationsOptions } from "./src/types.js";
+export { parseBibliography } from "./src/bibliography.js";
+export { remarkCitations } from "./src/remark.js";
+export type { BibliographyEntry, CitationOccurrence, CitationReference, CitationSyntax, CitationsOptions, ResolvedCitation, } from "./src/types.js";
+export declare function citations(options?: CitationsOptions): import("@riebeckite/core").RiebeckitePlugin<CitationsOptions>;
+export declare const citationsPlugin: typeof citations;

package/dist/index.js

@@ -0,0 +1,745 @@
+// index.ts
+import {
+  definePlugin,
+  readContentSourceEntry
+} from "@riebeckite/core";
+
+// src/remark.ts
+import { visit } from "unist-util-visit";
+
+// src/bibliography.ts
+var SUPPORTED_TYPES = /* @__PURE__ */ new Set(["article", "book", "inproceedings", "misc"]);
+var NON_ENTRY_TYPES = /* @__PURE__ */ new Set(["comment", "preamble", "string"]);
+var BUILTIN_MACROS = /* @__PURE__ */ new Set([
+  "jan",
+  "feb",
+  "mar",
+  "apr",
+  "may",
+  "jun",
+  "jul",
+  "aug",
+  "sep",
+  "oct",
+  "nov",
+  "dec"
+]);
+function parseBibliography(source, filePath = "bibliography") {
+  const text = source.replace(/\r\n?/g, "\n");
+  const entries = /* @__PURE__ */ new Map();
+  const diagnostics = [];
+  let index = 0;
+  while (index < text.length) {
+    const at = text.indexOf("@", index);
+    if (at < 0) break;
+    const parsed = parseEntry(text, at, filePath);
+    if (parsed.kind === "ignored") {
+      index = at + 1;
+      continue;
+    }
+    if (parsed.kind === "malformed") {
+      diagnostics.push({
+        code: "citation-malformed-bibliography",
+        severity: "error",
+        message: `Malformed bibliography entry in ${filePath}: ${parsed.reason}`,
+        filePath
+      });
+      index = at + 1;
+      continue;
+    }
+    index = parsed.nextIndex;
+    if (parsed.kind === "skipped") continue;
+    const { entry } = parsed;
+    if (entries.has(entry.key)) {
+      diagnostics.push({
+        code: "citation-duplicate-key",
+        severity: "warning",
+        message: `Duplicate bibliography key: ${entry.key}`,
+        filePath,
+        target: entry.key
+      });
+      continue;
+    }
+    if (!SUPPORTED_TYPES.has(entry.type)) {
+      diagnostics.push({
+        code: "citation-unsupported-entry-type",
+        severity: "warning",
+        message: `Bibliography entry type "${entry.type}" is not fully supported; "${entry.key}" is rendered with generic fields.`,
+        filePath,
+        target: entry.key
+      });
+    }
+    diagnostics.push(...parsed.diagnostics);
+    entries.set(entry.key, entry);
+  }
+  return { entries, diagnostics };
+}
+function parseEntry(text, start, filePath) {
+  const typeMatch = /^@([A-Za-z]+)\s*[{(]/.exec(text.slice(start));
+  if (!typeMatch) return { kind: "ignored" };
+  const type = typeMatch[1].toLowerCase();
+  const bodyStart = start + typeMatch[0].length;
+  const close = findEntryClose(text, bodyStart - 1);
+  if (close < 0) return { kind: "malformed", reason: "unterminated entry" };
+  const body = text.slice(bodyStart, close).trim();
+  if (NON_ENTRY_TYPES.has(type)) {
+    return { kind: "skipped", nextIndex: close + 1 };
+  }
+  const comma = findTopLevelComma(body);
+  if (comma < 0) {
+    return { kind: "malformed", reason: `entry "${type}" has no citation key` };
+  }
+  const key = body.slice(0, comma).trim();
+  if (!key) return { kind: "malformed", reason: "empty citation key" };
+  const fields = parseFields(body.slice(comma + 1), key, filePath);
+  return {
+    kind: "entry",
+    entry: { key, type, fields: fields.fields },
+    nextIndex: close + 1,
+    diagnostics: fields.diagnostics
+  };
+}
+function findEntryClose(text, openIndex) {
+  const open = text[openIndex];
+  let depth = 0;
+  let braceDepth = 0;
+  let quoted = false;
+  for (let index = openIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"' && text[index - 1] !== "\\") {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) continue;
+    if (open === "{") {
+      if (char === "{") depth += 1;
+      else if (char === "}") {
+        depth -= 1;
+        if (depth === 0) return index;
+      }
+      continue;
+    }
+    if (char === "{") {
+      braceDepth += 1;
+      continue;
+    }
+    if (char === "}") {
+      braceDepth -= 1;
+      continue;
+    }
+    if (braceDepth > 0) continue;
+    if (char === "(") depth += 1;
+    else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+function findTopLevelComma(input) {
+  let braceDepth = 0;
+  let quoted = false;
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (char === '"' && input[index - 1] !== "\\") {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) continue;
+    if (char === "{") braceDepth += 1;
+    else if (char === "}") braceDepth -= 1;
+    else if (char === "," && braceDepth <= 0) return index;
+  }
+  return -1;
+}
+function parseFields(input, target, filePath) {
+  const fields = {};
+  const diagnostics = [];
+  let index = 0;
+  while (index < input.length) {
+    const matcher = /\s*([A-Za-z][A-Za-z0-9_-]*)\s*=\s*/y;
+    matcher.lastIndex = index;
+    const field = matcher.exec(input);
+    if (!field) {
+      const rest = input.slice(index).replace(/[\s,]+/g, "");
+      if (rest) {
+        diagnostics.push(
+          unsupportedSyntax(
+            `Unexpected text "${rest}" where a field was expected`,
+            target,
+            filePath
+          )
+        );
+      }
+      break;
+    }
+    const name = field[1].toLowerCase();
+    const value = readValue(input, matcher.lastIndex);
+    fields[name] = cleanValue(value.value);
+    if (value.unclosed) {
+      diagnostics.push({
+        code: "citation-malformed-bibliography",
+        severity: "error",
+        message: `Unclosed ${value.opener === "{" ? "braced" : "quoted"} value for field "${name}" in "${filePath}".`,
+        filePath,
+        target
+      });
+      break;
+    }
+    let nextIndex = value.nextIndex;
+    if (isConcatenation(input, nextIndex)) {
+      diagnostics.push(
+        unsupportedSyntax(
+          `String concatenation in field "${name}" is not supported`,
+          target,
+          filePath
+        )
+      );
+      nextIndex = scanToTopLevelComma(input, nextIndex);
+    } else if (isUnresolvedMacro(value)) {
+      diagnostics.push(
+        unsupportedSyntax(
+          `BibTeX macro "${value.value}" in field "${name}" is not expanded and is rendered literally`,
+          target,
+          filePath
+        )
+      );
+    }
+    index = nextIndex;
+    while (input[index] && /[\s,]/.test(input[index])) index += 1;
+  }
+  return { fields, diagnostics };
+}
+function readValue(input, start) {
+  const opener = input[start];
+  if (opener === "{" || opener === '"') {
+    const closer = opener === "{" ? "}" : '"';
+    let depth = opener === "{" ? 1 : 0;
+    for (let index = start + 1; index < input.length; index += 1) {
+      const char = input[index];
+      if (opener === "{" && char === "{") depth += 1;
+      if (char === closer && input[index - 1] !== "\\") {
+        if (opener === '"' || depth === 1) {
+          return {
+            value: input.slice(start + 1, index),
+            nextIndex: index + 1,
+            delimited: true
+          };
+        }
+        depth -= 1;
+      }
+    }
+    return {
+      value: input.slice(start + 1),
+      nextIndex: input.length,
+      delimited: true,
+      unclosed: true,
+      opener
+    };
+  }
+  let end = start;
+  while (end < input.length && input[end] !== "," && input[end] !== "#") {
+    end += 1;
+  }
+  return {
+    value: input.slice(start, end).trim(),
+    nextIndex: end,
+    delimited: false
+  };
+}
+function isConcatenation(input, from) {
+  return input.slice(from).trimStart().startsWith("#");
+}
+function scanToTopLevelComma(input, from) {
+  let braceDepth = 0;
+  let quoted = false;
+  for (let index = from; index < input.length; index += 1) {
+    const char = input[index];
+    if (char === '"' && input[index - 1] !== "\\") {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) continue;
+    if (char === "{") braceDepth += 1;
+    else if (char === "}") braceDepth -= 1;
+    else if (char === "," && braceDepth <= 0) return index;
+  }
+  return input.length;
+}
+function isUnresolvedMacro(value) {
+  if (value.delimited) return false;
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(value.value)) return false;
+  return !BUILTIN_MACROS.has(value.value.toLowerCase());
+}
+function unsupportedSyntax(message, target, filePath) {
+  return {
+    code: "citation-unsupported-bibliography-syntax",
+    severity: "warning",
+    message: `${message} in "${filePath}".`,
+    filePath,
+    target
+  };
+}
+function cleanValue(value) {
+  return value.replace(/[{}]/g, "").replace(/\\([&%$#_{}])/g, "$1").trim();
+}
+
+// src/remark.ts
+var BLOCKING_ANCESTORS = /* @__PURE__ */ new Set([
+  "link",
+  "linkReference",
+  "definition",
+  "inlineCode",
+  "code",
+  "html",
+  "yaml",
+  "toml"
+]);
+function remarkCitations(options) {
+  return async (tree, file) => {
+    const blocked = /* @__PURE__ */ new WeakSet();
+    prepareTree(tree, blocked);
+    const paths = bibliographyPathGroups(options, readFrontmatter(file));
+    const bibliography = await loadBibliographies(paths, options);
+    const context = createRenderContext(options, bibliography.entries);
+    visit(
+      tree,
+      "text",
+      (node, index, parent) => {
+        if (index === void 0 || !parent.children) return;
+        if (blocked.has(node)) return;
+        const replacement = transformTextNode(node, context);
+        if (replacement.length === 1 && replacement[0] === node) return;
+        parent.children.splice(index, 1, ...replacement);
+        return index + replacement.length;
+      }
+    );
+    if (context.orderedKeys.length > 0) {
+      tree.children.push(createReferencesHeading(options.referencesHeading));
+      tree.children.push(createReferencesList(context));
+    }
+  };
+}
+function readFrontmatter(file) {
+  const matter = file.data?.matter;
+  return typeof matter === "object" && matter !== null ? matter : void 0;
+}
+function prepareTree(root, blocked) {
+  prepareNode(root, blocked, false);
+}
+function prepareNode(node, blocked, insideBlocked) {
+  const children = node.children;
+  if (!children) return;
+  const isBlocked = insideBlocked || node.type !== void 0 && BLOCKING_ANCESTORS.has(node.type);
+  if (!isBlocked) repairSplitCitations(children);
+  for (const child of children) {
+    if (!child || typeof child !== "object") continue;
+    const candidate = child;
+    if (candidate.type === "text") {
+      if (isBlocked) blocked.add(candidate);
+      continue;
+    }
+    prepareNode(candidate, blocked, isBlocked);
+  }
+}
+function repairSplitCitations(children) {
+  for (let index = 1; index < children.length; index += 1) {
+    const node = children[index];
+    if (node?.type !== "textDirective") continue;
+    const previous = children[index - 1];
+    if (previous?.type !== "text" || typeof previous.value !== "string") {
+      continue;
+    }
+    if (Array.isArray(node.children) && node.children.length > 0) continue;
+    if (node.attributes && Object.keys(node.attributes).length > 0) continue;
+    const junction = previous.value.length;
+    const following = children[index + 1];
+    const followingValue = following?.type === "text" && typeof following.value === "string" ? following.value : "";
+    const merged = `${previous.value}:${node.name ?? ""}${followingValue}`;
+    if (!spansCitation(merged, junction)) continue;
+    previous.value = merged;
+    if (followingValue) children.splice(index + 1, 1);
+    children.splice(index, 1);
+    index -= 1;
+  }
+}
+function spansCitation(value, junction) {
+  return findCitations(value).some(
+    (match) => match.start < junction && match.end > junction
+  );
+}
+function bibliographyPathGroups(options, frontmatter) {
+  if (frontmatter?.bibliography !== void 0) {
+    return pathList(frontmatter.bibliography).map(
+      (path) => pageRelativeCandidates(path, options.sourceSlug)
+    );
+  }
+  return pathList(options.bibliography).map((path) => [path]);
+}
+function pathList(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string");
+  }
+  return [];
+}
+function pageRelativeCandidates(path, sourceSlug) {
+  const normalized = normalizeLogicalPath(path);
+  if (!sourceSlug || isAbsoluteLikePath(normalized)) return [normalized];
+  const directory = normalizeLogicalPath(sourceSlug).split("/").slice(0, -1).join("/");
+  if (!directory) return [normalized];
+  const relative = normalizeLogicalPath(`${directory}/${normalized}`);
+  return relative === normalized ? [normalized] : [relative, normalized];
+}
+function isAbsoluteLikePath(path) {
+  return path.startsWith("/") || /^[A-Za-z]:\//.test(path);
+}
+function normalizeLogicalPath(path) {
+  const parts = [];
+  for (const segment of path.replace(/\\/g, "/").split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (parts.length > 0 && parts.at(-1) !== "..") parts.pop();
+      else parts.push(segment);
+      continue;
+    }
+    parts.push(segment);
+  }
+  const prefix = path.startsWith("/") ? "/" : "";
+  return `${prefix}${parts.join("/")}`;
+}
+async function loadBibliographies(pathGroups, options) {
+  const entries = /* @__PURE__ */ new Map();
+  const diagnostics = [];
+  for (const candidates of pathGroups) {
+    const resolved = await loadFirstAvailable(candidates, options);
+    if (!resolved) {
+      diagnostics.push({
+        code: "citation-missing-bibliography",
+        severity: "error",
+        message: `Bibliography file was not found: ${candidates[0] ?? ""}`,
+        filePath: candidates[0]
+      });
+      continue;
+    }
+    diagnostics.push(...resolved.parsed.diagnostics);
+    for (const [key, entry] of resolved.parsed.entries) {
+      if (entries.has(key)) {
+        diagnostics.push({
+          code: "citation-duplicate-key",
+          severity: "warning",
+          message: `Duplicate bibliography key: ${key}`,
+          filePath: resolved.path,
+          target: key
+        });
+      } else {
+        entries.set(key, entry);
+      }
+    }
+  }
+  pushUniqueDiagnostics(options.diagnostics, diagnostics, options.sourceSlug);
+  return { entries, diagnostics };
+}
+async function loadFirstAvailable(candidates, options) {
+  for (const path of candidates) {
+    const resolved = await cachedBibliography(path, options);
+    if (resolved.found) return { path, parsed: resolved.parsed };
+  }
+  return null;
+}
+async function cachedBibliography(path, options) {
+  const cached = options.cache.get(path);
+  if (cached) return cached;
+  const promise = (async () => {
+    const source = await options.loadBibliography(path);
+    if (source === null) {
+      return {
+        found: false,
+        parsed: { entries: /* @__PURE__ */ new Map(), diagnostics: [] }
+      };
+    }
+    return { found: true, parsed: parseBibliography(source, path) };
+  })();
+  options.cache.set(path, promise);
+  return promise;
+}
+function createRenderContext(options, entries) {
+  return {
+    entries,
+    numbers: /* @__PURE__ */ new Map(),
+    orderedKeys: [],
+    referenceIds: /* @__PURE__ */ new Map(),
+    usedReferenceIds: /* @__PURE__ */ new Set(),
+    occurrences: [],
+    options
+  };
+}
+function transformTextNode(node, context) {
+  const segments = [];
+  let cursor = 0;
+  for (const match of findCitations(node.value)) {
+    if (match.start > cursor)
+      segments.push({
+        type: "text",
+        value: node.value.slice(cursor, match.start)
+      });
+    segments.push(renderCitation(match.references, match.bracketed, context));
+    cursor = match.end;
+  }
+  if (segments.length === 0) return [node];
+  if (cursor < node.value.length)
+    segments.push({ type: "text", value: node.value.slice(cursor) });
+  return segments;
+}
+function findCitations(value) {
+  const matches = [];
+  const ignoredRanges = findWikiLinkRanges(value);
+  const bracketPattern = /\[([^\]]*@[-A-Za-z0-9_:.]+[^\]]*)\]/g;
+  for (const match of value.matchAll(bracketPattern)) {
+    if (value[match.index - 1] === "[" || value[match.index + match[0].length] === "]") {
+      continue;
+    }
+    if (rangeOverlaps(ignoredRanges, match.index, match.index + match[0].length))
+      continue;
+    const references = parseBracketCitation(match[1]);
+    if (references.length === 0) continue;
+    matches.push({
+      start: match.index,
+      end: match.index + match[0].length,
+      references,
+      bracketed: true
+    });
+  }
+  const inlinePattern = /(^|[\s(])@([-A-Za-z0-9_:.]+)(?=\b)/g;
+  for (const match of value.matchAll(inlinePattern)) {
+    const start = match.index + match[1].length;
+    if (rangeOverlaps(ignoredRanges, start, start + match[2].length + 1))
+      continue;
+    if (overlaps(matches, start, start + match[2].length + 1)) continue;
+    matches.push({
+      start,
+      end: start + match[2].length + 1,
+      bracketed: false,
+      references: [{ key: match[2], suppressAuthor: false }]
+    });
+  }
+  return matches.toSorted((a, b) => a.start - b.start);
+}
+function findWikiLinkRanges(value) {
+  const ranges = [];
+  const pattern = /\[\[[\s\S]*?\]\]/g;
+  for (const match of value.matchAll(pattern)) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+  return ranges;
+}
+function rangeOverlaps(ranges, start, end) {
+  return ranges.some((range) => start < range.end && end > range.start);
+}
+function parseBracketCitation(input) {
+  return input.split(";").map((part) => parseCitationPart(part.trim())).filter((part) => Boolean(part));
+}
+function parseCitationPart(part) {
+  const match = /^(?<prefix>.*?)\s*(?<suppress>-?)@(?<key>[-A-Za-z0-9_:.]+)(?<suffix>.*)$/.exec(
+    part
+  );
+  if (!match?.groups) return null;
+  return {
+    key: match.groups.key,
+    prefix: match.groups.prefix.trim() || void 0,
+    suffix: match.groups.suffix.trim() || void 0,
+    suppressAuthor: match.groups.suppress === "-"
+  };
+}
+function overlaps(matches, start, end) {
+  return matches.some((match) => start < match.end && end > match.start);
+}
+function renderCitation(references, bracketed, context) {
+  const renderedReferences = references.map(
+    (reference) => renderCitationReference(reference, context)
+  );
+  const separator = renderedReferences.some((item) => item.hasAffix) ? "; " : ", ";
+  const text = renderedReferences.map((item) => item.text).join(separator);
+  const label = bracketed ? `[${text}]` : text;
+  const occurrenceId = `citation-${context.options.sourceSlug ?? "page"}-${context.occurrences.length + 1}`.replace(
+    /[^A-Za-z0-9_-]/g,
+    "-"
+  );
+  context.occurrences.push({
+    id: occurrenceId,
+    pageSlug: context.options.sourceSlug,
+    references,
+    label,
+    syntax: bracketed ? references.some((item) => item.suppressAuthor) ? "suppress-author" : "bracket" : "inline"
+  });
+  return {
+    type: "link",
+    url: `#${referenceId(references[0]?.key ?? "unknown", context)}`,
+    title: null,
+    children: [{ type: "text", value: label }]
+  };
+}
+function renderCitationReference(reference, context) {
+  const number = numberForReference(reference, context).toString();
+  return {
+    text: citationReferenceText(reference.prefix, number, reference.suffix),
+    hasAffix: Boolean(reference.prefix || reference.suffix)
+  };
+}
+function citationReferenceText(prefix, number, suffix) {
+  const withPrefix = prefix ? `${prefix} ${number}` : number;
+  if (!suffix) return withPrefix;
+  return /^[,.;:)]/.test(suffix) ? `${withPrefix}${suffix}` : `${withPrefix} ${suffix}`;
+}
+function numberForReference(reference, context) {
+  const existing = context.numbers.get(reference.key);
+  if (existing) return existing;
+  const number = context.orderedKeys.length + 1;
+  context.numbers.set(reference.key, number);
+  context.orderedKeys.push(reference.key);
+  referenceId(reference.key, context);
+  if (!context.entries.has(reference.key)) {
+    pushUniqueDiagnostics(
+      context.options.diagnostics,
+      [
+        {
+          code: "citation-unknown-key",
+          severity: "warning",
+          message: `Unknown citation key: ${reference.key}`,
+          slug: context.options.sourceSlug,
+          target: reference.key
+        }
+      ],
+      context.options.sourceSlug
+    );
+  }
+  return number;
+}
+function referenceId(key, context) {
+  const existing = context.referenceIds.get(key);
+  if (existing) return existing;
+  const sanitized = key.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  const base = `ref-${sanitized || "key"}`;
+  let id = base;
+  let counter = 2;
+  while (context.usedReferenceIds.has(id)) {
+    id = `${base}-${counter}`;
+    counter += 1;
+  }
+  context.referenceIds.set(key, id);
+  context.usedReferenceIds.add(id);
+  return id;
+}
+function createReferencesHeading(text = "References") {
+  return {
+    type: "heading",
+    depth: 2,
+    children: [{ type: "text", value: text }]
+  };
+}
+function createReferencesList(context) {
+  return {
+    type: "list",
+    ordered: true,
+    start: 1,
+    spread: false,
+    children: context.orderedKeys.map(
+      (key) => ({
+        type: "listItem",
+        spread: false,
+        data: { hProperties: { id: referenceId(key, context) } },
+        children: [
+          {
+            type: "paragraph",
+            children: [
+              {
+                type: "text",
+                value: renderBibliographyEntry(context.entries.get(key), key)
+              }
+            ]
+          }
+        ]
+      })
+    )
+  };
+}
+function renderBibliographyEntry(entry, key) {
+  if (!entry) return key;
+  const author = entry.fields.author ?? entry.fields.editor;
+  const year = entry.fields.year ?? entry.fields.date;
+  const title = entry.fields.title;
+  const container = entry.fields.journal ?? entry.fields.booktitle ?? entry.fields.publisher;
+  return [author, year ? `(${year})` : void 0, title, container].filter(Boolean).join(". ");
+}
+function pushUniqueDiagnostics(target, diagnostics, slug) {
+  for (const diagnostic of diagnostics) {
+    const next = diagnostic.slug ? diagnostic : { ...diagnostic, slug };
+    const signature = diagnosticSignature(next);
+    if (target.some((item) => diagnosticSignature(item) === signature))
+      continue;
+    target.push(next);
+  }
+}
+function diagnosticSignature(diagnostic) {
+  return `${diagnostic.code}:${diagnostic.slug ?? ""}:${diagnostic.filePath ?? ""}:${diagnostic.target ?? ""}:${diagnostic.message}`;
+}
+
+// src/state.ts
+function createCitationState() {
+  return { bibliographies: /* @__PURE__ */ new Map(), diagnostics: [] };
+}
+
+// index.ts
+var PLUGIN_NAME = "citations";
+function citations(options = {}) {
+  const state = createCitationState();
+  return definePlugin({
+    name: PLUGIN_NAME,
+    options,
+    validateOptions: validateCitationsOptions,
+    extendMarkdownPipeline: (pipeline, context) => {
+      pipeline.use(remarkCitations, {
+        ...options,
+        sourceSlug: context.sourceSlug,
+        contentSource: context.contentSource,
+        diagnostics: state.diagnostics,
+        loadBibliography: async (path) => {
+          if (!context.contentSource) return null;
+          const content = await readContentSourceEntry(
+            context.contentSource,
+            path
+          );
+          if (content === null) return null;
+          return typeof content === "string" ? content : new TextDecoder().decode(content);
+        },
+        cache: state.bibliographies
+      });
+    },
+    addDiagnostics: () => state.diagnostics
+  });
+}
+var citationsPlugin = citations;
+function validateCitationsOptions(options) {
+  if (!options) return [];
+  const issues = [];
+  if (options.bibliography !== void 0) {
+    const value = options.bibliography;
+    const valid = typeof value === "string" || Array.isArray(value) && value.every((item) => typeof item === "string");
+    if (!valid) {
+      issues.push({
+        path: "bibliography",
+        message: "Expected a bibliography path or an array of paths."
+      });
+    }
+  }
+  if (options.referencesHeading !== void 0 && typeof options.referencesHeading !== "string") {
+    issues.push({ path: "referencesHeading", message: "Expected a string." });
+  }
+  return issues;
+}
+export {
+  citations,
+  citationsPlugin,
+  parseBibliography,
+  remarkCitations
+};

package/dist/src/bibliography.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedBibliography } from "./types.js";
+export declare function parseBibliography(source: string, filePath?: string): ParsedBibliography;

package/dist/src/remark.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from "mdast";
+import type { RemarkCitationsOptions } from "./types.js";
+type MarkdownFile = {
+    data?: Record<string, unknown>;
+};
+export declare function remarkCitations(options: RemarkCitationsOptions): (tree: Root, file: MarkdownFile) => Promise<void>;
+export {};

package/dist/src/state.d.ts

@@ -0,0 +1,7 @@
+import type { Diagnostic } from "@riebeckite/core";
+import type { BibliographyCache } from "./types.js";
+export type CitationState = {
+    readonly bibliographies: BibliographyCache;
+    readonly diagnostics: Diagnostic[];
+};
+export declare function createCitationState(): CitationState;

package/dist/src/types.d.ts

@@ -0,0 +1,46 @@
+import type { ContentSource, Diagnostic } from "@riebeckite/core";
+export type CitationsOptions = {
+    /** Vault-relative BibTeX/BibLaTeX file path or paths. */
+    bibliography?: string | readonly string[];
+    /** Heading inserted above generated references. Defaults to "References". */
+    referencesHeading?: string;
+};
+export type BibliographyEntry = {
+    readonly key: string;
+    readonly type: "article" | "book" | "inproceedings" | "misc" | string;
+    readonly fields: Readonly<Record<string, string>>;
+};
+export type CitationSyntax = "bracket" | "inline" | "suppress-author";
+export type CitationReference = {
+    readonly key: string;
+    readonly prefix?: string;
+    readonly suffix?: string;
+    readonly suppressAuthor: boolean;
+};
+export type CitationOccurrence = {
+    readonly id: string;
+    readonly pageSlug?: string;
+    readonly references: readonly CitationReference[];
+    readonly label: string;
+    readonly syntax: CitationSyntax;
+};
+export type ResolvedCitation = CitationReference & {
+    readonly entry?: BibliographyEntry;
+    readonly number?: number;
+};
+export type ParsedBibliography = {
+    readonly entries: ReadonlyMap<string, BibliographyEntry>;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export type CachedBibliography = {
+    readonly found: boolean;
+    readonly parsed: ParsedBibliography;
+};
+export type BibliographyCache = Map<string, Promise<CachedBibliography>>;
+export type RemarkCitationsOptions = CitationsOptions & {
+    readonly sourceSlug?: string;
+    readonly contentSource?: ContentSource;
+    readonly diagnostics: Diagnostic[];
+    readonly cache: BibliographyCache;
+    readonly loadBibliography: (path: string) => Promise<string | null>;
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@riebeckite/plugin-citations",
+  "version": "0.0.14",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@types/mdast": "^4.0.4",
+    "unist-util-visit": "^5.1.0",
+    "@riebeckite/core": "0.0.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/citations"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "BibTeX and BibLaTeX citation rendering for Riebeckite Markdown content.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "citations",
+    "bibtex",
+    "markdown"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs",
+    "test": "node --import tsx --test \"test/*.test.ts\""
+  }
+}