Riebeckite
Menu
Color mode

Citations

日本語版

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

History

1 changesCollapseExpand
1 + <!-- Generated from packages/plugins/citations/README.md. Do not edit this page directly; edit the package README and run `pnpm docs:sync`. -->
2 +
3 + # Citations
4 +
5 + [日本語版](./citations.md)
6 +
7 + Official Riebeckite plugin for BibTeX / BibLaTeX based citations in Markdown and Obsidian notes.
8 +
9 + ```ts
10 + import { citations } from "@riebeckite/plugin-citations";
11 +
12 + export default {
13 + plugins: [
14 + citations({ bibliography: "references.bib" }),
15 + ],
16 + };
17 + ```
18 +
19 + ## Supported citation syntax
20 +
21 + The plugin implements a stable Pandoc-inspired subset:
22 +
23 + - `[@smith2024]`
24 + - `[@smith2024; @doe2025]` — multiple keys must be separated by `;`
25 + - `@smith2024 argues that ...`
26 + - `[-@smith2024]` — suppress-author input
27 + - `[@smith2024, p. 42]` and `[see @doe2025]` — prefix and suffix are kept, rendering as `[1, p. 42]` and `[see 2]`
28 +
29 + Repeated citations reuse the first number assigned to that key. Under numeric labels, `[-@smith2024]` renders the same label as `[@smith2024]`.
30 +
31 + 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.
32 +
33 + 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 `.`.
34 +
35 + Not transformed: inline code, fenced code blocks, HTML, frontmatter, normal Markdown links (at any nesting depth), and Obsidian WikiLinks.
36 +
37 + ## Bibliography files
38 +
39 + - `citations({ bibliography })` paths are relative to the content root.
40 + - 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.
41 + - The bibliography file is read at build time only. It is never copied into the output and absolute paths never appear in generated files.
42 +
43 + ## Supported bibliography subset
44 +
45 + 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`.
46 +
47 + `@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.
48 +
49 + Supported syntax: multiline fields, quoted and braced values, nested braces, commas inside values, escaped characters, trailing commas, whitespace and CRLF.
50 +
51 + Reported through `citation-unsupported-bibliography-syntax` instead of failing silently:
52 +
53 + - `@string` macro references are rendered literally; they are not expanded.
54 + - `#` string concatenation keeps only the first part.
55 +
56 + ## References section
57 +
58 + 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.
59 +
60 + Use `referencesHeading` for localized headings:
61 +
62 + ```ts
63 + citations({ bibliography: "references.bib", referencesHeading: "参考文献" })
64 + ```
65 +
66 + ## Diagnostics
67 +
68 + Reported through Riebeckite diagnostics:
69 +
70 + - `citation-unknown-key`
71 + - `citation-missing-bibliography`
72 + - `citation-malformed-bibliography`
73 + - `citation-duplicate-key`
74 + - `citation-unsupported-entry-type`
75 + - `citation-unsupported-bibliography-syntax`
76 +
77 + Citation numbering, reference ordering, generated HTML, and diagnostics are deterministic: identical input produces identical output.
78 +
79 + ## License
80 +
81 + Apache-2.0
82 +