Citations

Citations は、Markdown / Obsidian ノートで BibTeX / BibLaTeX の文献情報を使えるようにする Plugin です。本文中の引用を番号に変換し、ページ末尾に参考文献リストを追加します。

導入

npm install @riebeckite/plugin-citations

import { citations } from "@riebeckite/plugin-citations";
 
export default defineConfig({
  plugins: [citations({ bibliography: "references.bib" })],
});

ページごとに文献ファイルを変えたい場合は frontmatter に書けます。

bibliography: references.bib

frontmatter のパスは、まずページからの相対パス、次にコンテンツルートからの相対パスとして解決します。config 側のパスは常にコンテンツルート基準です。

引用の書き方

Pandoc の記法を参考にした、扱いやすい範囲をサポートします。

[@smith2024]
[@smith2024; @doe2025]
@smith2024 argues that ...
[-@smith2024]（著者名を出さない形の入力）

prefix / suffix は保持されます。[@smith2024, p. 42] は [1, p. 42]、[see @doe2025] は [see 2] として表示します。同じ文献を何度も引用した場合は、最初に割り当てた番号を再利用します。

本文中の @key は左に境界が必要です。テキストの先頭、空白、( のいずれかにしてください。本文@smith2024 のように左がつながっている場合は [@smith2024] を書きます。

キーに使えるのは英字、数字、-、_、:、. です。Riebeckite の directive 構文が消費してしまう : はプラグインが組み直すため、[@colon:2024] も動きます。

参考文献リスト

引用があるページでは、本文の末尾に References セクションを追加します。引用番号から、引用キーから作った安定したアンカーへ移動できます。

日本語サイトでは見出しを変えられます。

citations({ bibliography: "references.bib", referencesHeading: "参考文献" })

対応する文献種別

重点的に扱うのは article、book、inproceedings、misc です。それ以外の種別も汎用フィールドとして読み込んで表示し、diagnostics に出します。@comment、@preamble、@string は受け付けて読み飛ばします。

複数行フィールド、引用符と波括弧の値、ネストした波括弧、値の中のカンマ、エスケープ文字、末尾カンマ、CRLF に対応します。マクロ展開と # による文字列連結は対象外で、壊れたまま無視せず diagnostics に報告します。

diagnostics

文献ファイルが見つからない、BibTeX が壊れている、引用キーが重複している、存在しない引用キーを使っている、未対応の文献種別や構文がある、といった問題を Riebeckite の diagnostics に出力します。

inline code、code block、HTML、frontmatter、通常の Markdown リンク、WikiLink の中は変換しません。

詳細仕様

設定項目、公開 API、制約、追加の使用例は package README を参照してください。Plugin 全体の仕組みは Plugin System を参照してください。

History

1 changesCollapseExpand

From To

	1	`+ # Citations`
	2	`+`
	3	`+ Citations は、Markdown / Obsidian ノートで BibTeX / BibLaTeX の文献情報を使えるようにする Plugin です。本文中の引用を番号に変換し、ページ末尾に参考文献リストを追加します。`
	4	`+`
	5	`+ ## 導入`
	6	`+`
	7	+ ```bash
	8	`+ npm install @riebeckite/plugin-citations`
	9	+ ```
	10	`+`
	11	+ ```ts
	12	`+ import { citations } from "@riebeckite/plugin-citations";`
	13	`+`
	14	`+ export default defineConfig({`
	15	`+ plugins: [citations({ bibliography: "references.bib" })],`
	16	`+ });`
	17	+ ```
	18	`+`
	19	`+ ページごとに文献ファイルを変えたい場合は frontmatter に書けます。`
	20	`+`
	21	+ ```yaml
	22	`+ bibliography: references.bib`
	23	+ ```
	24	`+`
	25	`+ frontmatter のパスは、まずページからの相対パス、次にコンテンツルートからの相対パスとして解決します。config 側のパスは常にコンテンツルート基準です。`
	26	`+`
	27	`+ ## 引用の書き方`
	28	`+`
	29	`+ Pandoc の記法を参考にした、扱いやすい範囲をサポートします。`
	30	`+`
	31	+ - `[@smith2024]`
	32	+ - `[@smith2024; @doe2025]`
	33	+ - `@smith2024 argues that ...`
	34	+ - `[-@smith2024]`（著者名を出さない形の入力）
	35	`+`
	36	+ prefix / suffix は保持されます。`[@smith2024, p. 42]` は `[1, p. 42]`、`[see @doe2025]` は `[see 2]` として表示します。同じ文献を何度も引用した場合は、最初に割り当てた番号を再利用します。
	37	`+`
	38	+ 本文中の `@key` は左に境界が必要です。テキストの先頭、空白、`(` のいずれかにしてください。`本文@smith2024` のように左がつながっている場合は `[@smith2024]` を書きます。
	39	`+`
	40	+ キーに使えるのは英字、数字、`-`、`_`、`:`、`.` です。Riebeckite の directive 構文が消費してしまう `:` はプラグインが組み直すため、`[@colon:2024]` も動きます。
	41	`+`
	42	`+ ## 参考文献リスト`
	43	`+`
	44	+ 引用があるページでは、本文の末尾に `References` セクションを追加します。引用番号から、引用キーから作った安定したアンカーへ移動できます。
	45	`+`
	46	`+ 日本語サイトでは見出しを変えられます。`
	47	`+`
	48	+ ```ts
	49	`+ citations({ bibliography: "references.bib", referencesHeading: "参考文献" })`
	50	+ ```
	51	`+`
	52	`+ ## 対応する文献種別`
	53	`+`
	54	+ 重点的に扱うのは `article`、`book`、`inproceedings`、`misc` です。それ以外の種別も汎用フィールドとして読み込んで表示し、diagnostics に出します。`@comment`、`@preamble`、`@string` は受け付けて読み飛ばします。
	55	`+`
	56	+ 複数行フィールド、引用符と波括弧の値、ネストした波括弧、値の中のカンマ、エスケープ文字、末尾カンマ、CRLF に対応します。マクロ展開と `#` による文字列連結は対象外で、壊れたまま無視せず diagnostics に報告します。
	57	`+`
	58	`+ ## diagnostics`
	59	`+`
	60	`+ 文献ファイルが見つからない、BibTeX が壊れている、引用キーが重複している、存在しない引用キーを使っている、未対応の文献種別や構文がある、といった問題を Riebeckite の diagnostics に出力します。`
	61	`+`
	62	`+ inline code、code block、HTML、frontmatter、通常の Markdown リンク、WikiLink の中は変換しません。`
	63	`+`
	64	`+ ## 詳細仕様`
	65	`+`
	66	`+ 設定項目、公開 API、制約、追加の使用例は package README を参照してください。Plugin 全体の仕組みは [Plugin System](../framework/plugin-system.ja.md) を参照してください。`
	67	`+`
	68	`+`