@riebeckite/plugin-citations 0.0.31 → 0.0.33

package/README.md

@@ -34,6 +34,20 @@ Riebeckite parses `:name` as a directive before this plugin runs. When that spli
 
 Not transformed: inline code, fenced code blocks, HTML, frontmatter, normal Markdown links (at any nesting depth), and Obsidian WikiLinks.
 
+## Live example
+
+The citations below use the site bibliography.
+
+Riebeckite builds on Markdown[@gruber2004] and ships its own plugin model.[@riebeckite2026]
+
+Several sources can be cited together.[@riebeckite2026; @gruber2004]
+
+An author-integrated citation: @gruber2004 argues that readable source matters.
+
+A suppressed-author citation: [-@riebeckite2026] keeps the number.
+
+A locator and prefix: [see @riebeckite2026, p. 42].
+
 ## Bibliography files
 
 - `citations({ bibliography })` paths are relative to the content root.

package/README_ja.md

@@ -18,37 +18,51 @@ export default {
 
 ## 対応する引用の記法
 
-Pandoc を参考にした、安定した一部の記法を扱います。
+Pandoc を参考にした、安定した記法のサブセットを扱います。
 
 - `[@smith2024]`
 - `[@smith2024; @doe2025]`：複数のキーは `;` で区切る
 - `@smith2024 argues that ...`
 - `[-@smith2024]`：著者名を出さない形の入力
-- `[@smith2024, p. 42]` と `[see @doe2025]`：prefix / suffix を保持し、`[1, p. 42]` と `[see 2]` として表示する
+- `[@smith2024, p. 42]` と `[see @doe2025]`：接頭辞と接尾辞を保持し、`[1, p. 42]` と `[see 2]` として表示する
 
 同じ文献を何度も引用した場合は、最初に割り当てた番号を再利用します。番号形式の表示では `[-@smith2024]` と `[@smith2024]` のラベルは同じになります。
 
 本文中の `@key` は、テキストの先頭、空白、`(` のいずれかの直後に書きます。`本文@smith2024` のように `@key` の左が文字でつながっている形は認識されないため、`[@smith2024]` を使ってください。
 
-Riebeckite はこのプラグインより先に `:name` を directive として解釈します。directive 化によって引用キーが分断された場合はプラグインが組み直すため、`[@colon:2024]` と `@colon:2024 argues` の両方が動きます。キーに使えるのは英字、数字、`-`、`_`、`:`、`.` です。
+Riebeckite はこのプラグインより先に `:name` をディレクティブとして解釈します。ディレクティブ化で引用キーが分断された場合はプラグインが組み直すため、`[@colon:2024]` と `@colon:2024 argues` の両方が動きます。キーに使えるのは英字、数字、`-`、`_`、`:`、`.` です。
 
-変換しない対象: インラインコード、フェンスドコードブロック、HTML、frontmatter、任意の階層にある通常の Markdown リンク、Obsidian の Wikilink。
+変換しない対象: インラインコード、フェンス付きコードブロック、HTML、frontmatter、任意の階層にある通常の Markdown リンク、Obsidian の Wikilink。
+
+## 実行例
+
+以下の引用はサイトの文献ファイルを使っています。
+
+Riebeckite は Markdown を基盤にしています[@gruber2004]。また独自のプラグインモデルを持ちます。[@riebeckite2026]
+
+複数の文献をまとめて引用できます。[@riebeckite2026; @gruber2004]
+
+著者名を文中に置く引用: @gruber2004 は、読みやすいソースの重要性を説いています。
+
+著者名を省略する引用: [-@riebeckite2026] は番号だけを表示します。
+
+位置情報と接頭辞: [see @riebeckite2026, p. 42]。
 
 ## 文献ファイルの読み込み
 
 - `citations({ bibliography })` のパスはコンテンツルートからの相対パスです。
-- frontmatter の `bibliography` は、まずページからの相対パス、次にコンテンツルートからの相対パスとして解決します。`/` と `\` の両区切りを受け付け、`../` は文字列内で正規化します。候補はいずれも content source を通るため、設定されたコンテンツルートの外は読み込めません。
+- frontmatter の `bibliography` は、まずページからの相対パス、次にコンテンツルートからの相対パスとして解決します。`/` と `\` の両区切りを受け付け、`../` は文字列内で正規化します。候補はいずれもコンテンツソースを通るため、設定されたコンテンツルートの外は読み込めません。
 - 文献ファイルはビルド時に読み込むだけで、出力にはコピーされず、絶対パスも生成物に現れません。
 
 ## 対応する BibTeX の範囲
 
 重点的に扱う文献種別は `article`、`book`、`inproceedings`、`misc` です。その他の種別も汎用フィールドとして読み込んで表示し、`citation-unsupported-entry-type` として報告します。
 
-`@comment`、`@preamble`、`@string` は受け付けて読み飛ばします。壊れたエントリは `citation-malformed-bibliography` を出し、次の `@` から再開するため、1 件の不正でファイル残りが消えることはありません。
+`@comment`、`@preamble`、`@string` は受け付けて読み飛ばします。壊れたエントリは `citation-malformed-bibliography` を出し、次の `@` から再開するため、1 件の不正でファイルの残りが消えることはありません。
 
 対応する構文: 複数行フィールド、引用符と波括弧の値、ネストした波括弧、値の中のカンマ、エスケープ文字、末尾カンマ、空白、CRLF。
 
-次は沈黙せず `citation-unsupported-bibliography-syntax` として報告します。
+次の構文は黙って無視せず、`citation-unsupported-bibliography-syntax` として報告します。
 
 - `@string` のマクロ参照は展開せずそのまま文字列として表示する
 - `#` による文字列連結は先頭の部分しか保持しない
@@ -71,18 +85,18 @@ citations({ bibliography: "references.bib", referencesHeading: "参考文献" })
 citations({ bibliography: "references.bib", pagePath: "/bibliography" })
 ```
 
-ページタイプ（`citations-bibliography`）は、次の2か所から文献を集めます。
+ページタイプ（`citations-bibliography`）は、次の 2 か所から文献を集めます。
 
 - プラグインの `bibliography` オプション（コンテンツルートからの相対パス）
 - 公開（discoverable）ページの frontmatter `bibliography`
 
-frontmatter の `bibliography` を取り込むのは `manifest.discoverableEntries` だけです。下書き・unlisted・公開予定など、discoverable でないページは無視するため、それらの文献がページへ漏れることはありません。
+frontmatter の `bibliography` を取り込むのは `manifest.discoverableEntries` だけです。下書き、unlisted、公開予定など、公開対象でないページは無視するため、それらの文献がページへ漏れることはありません。
 
-各ファイルの文献は決定的な順序で統合します。内容まで同じ重複は黙って1件にまとめ、同じキーで内容が異なる場合は先に見つかった定義を採用し、`citation-duplicate-key` として報告します。ファイルが見つからない場合は `citation-missing-bibliography`、解析できない場合は `citation-malformed-bibliography` を報告します。文献が1件も集まらないときはページを生成しません。同じパスを Markdown ページやリダイレクトが既に持っている場合は Markdown を優先し、`citations-page-conflict` を報告してページを生成しません。
+各ファイルの文献は決定的な順序で統合します。内容まで同じ重複は黙って 1 件にまとめ、同じキーで内容が異なる場合は先に見つかった定義を採用し、`citation-duplicate-key` として報告します。ファイルが見つからない場合は `citation-missing-bibliography`、解析できない場合は `citation-malformed-bibliography` を報告します。文献が 1 件も集まらないときはページを生成しません。同じパスを Markdown ページやリダイレクトが既に持っている場合は Markdown を優先し、`citations-page-conflict` を報告してページを生成しません。
 
-ページ本文には専用の `<main>` と `<h1>` を持たせ、文献のテキストはすべてエスケープします。`url` と `doi` は安全な `http(s)` のときだけリンクにします。文献はキー順に並べます。既存の本文中の引用と `References` セクションは変更しません。
+ページ本文には専用の `<main>` と `<h1>` を持たせ、文献エントリのテキストはすべてエスケープします。`url` と `doi` は安全な `http(s)` のときだけリンクにします。文献はキー順に並べます。既存の本文中の引用と `References` セクションは変更しません。
 
-参考文献ページは `global` の output dependency を宣言します。文献ファイル、frontmatter の `bibliography`、ページの公開状態、`pagePath` の変更で、影響する出力を無効化します。
+参考文献ページはグローバルな出力依存（`global`）を宣言します。文献ファイル、frontmatter の `bibliography`、ページの公開状態、`pagePath` の変更で、影響する出力を無効化します。
 
 ## オプション
 
@@ -92,9 +106,9 @@ frontmatter の `bibliography` を取り込むのは `manifest.discoverableEntri
 | `referencesHeading` | `"References"` | 生成する参考文献の見出し |
 | `pagePath` | 未設定 | 参考文献一覧ページのパス。指定しないときは生成しない |
 
-## diagnostics
+## 診断
 
-以下を Riebeckite の diagnostics に出力します。
+以下を Riebeckite の診断として出力します。
 
 - `citation-unknown-key`
 - `citation-missing-bibliography`
@@ -103,7 +117,7 @@ frontmatter の `bibliography` を取り込むのは `manifest.discoverableEntri
 - `citation-unsupported-entry-type`
 - `citation-unsupported-bibliography-syntax`
 
-引用番号、参考文献の並び、生成される HTML、diagnostics の順序は決定的で、同じ入力からは同じ出力になります。
+引用番号、参考文献の並び、生成される HTML、診断の順序は決定的で、同じ入力からは同じ出力になります。
 
 ## ライセンス
 

package/dist/index.d.ts

@@ -3,4 +3,3 @@ 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

@@ -783,7 +783,7 @@ function renderCitation(references, bracketed, context) {
   });
   return {
     type: "link",
-    url: `#${referenceId2(references[0]?.key ?? "unknown", context)}`,
+    url: `#user-content-${referenceId2(references[0]?.key ?? "unknown", context)}`,
     title: null,
     children: [{ type: "text", value: label }]
   };
@@ -949,7 +949,6 @@ function citations(options = {}) {
     addDiagnostics: () => state.diagnostics
   });
 }
-var citationsPlugin = citations;
 function validateCitationsOptions(options) {
   if (!options) return [];
   const issues = [];
@@ -973,7 +972,6 @@ function validateCitationsOptions(options) {
 }
 export {
   citations,
-  citationsPlugin,
   parseBibliography,
   remarkCitations
 };

package/dist/src/page.d.ts

@@ -1,6 +1,6 @@
 import { type ContentManifest, type ContentSource, type Diagnostic, type PluginPage } from "@riebeckite/core";
 import type { CitationsOptions } from "./types.js";
-export type BibliographyPageSource = {
+type BibliographyPageSource = {
     readonly manifest: ContentManifest;
     readonly contentSource?: ContentSource;
     readonly diagnostics: Diagnostic[];
@@ -9,3 +9,4 @@ export declare function listBibliographyPagePaths(source: BibliographyPageSource
 export declare function resolveBibliographyPage(context: BibliographyPageSource & {
     readonly pathname: string;
 }, options: CitationsOptions): Promise<PluginPage | null>;
+export {};

package/dist/src/paths.d.ts

@@ -6,7 +6,5 @@ export declare function pathList(value: unknown): readonly string[];
  * escape the configured content root.
  */
 export declare function pageRelativeCandidates(path: string, sourceSlug: string | undefined): readonly string[];
-export declare function isAbsoluteLikePath(path: string): boolean;
 export declare function normalizeLogicalPath(path: string): string;
 export declare function pushUniqueDiagnostics(target: Diagnostic[], diagnostics: readonly Diagnostic[], slug: string | undefined): void;
-export declare function diagnosticSignature(diagnostic: Diagnostic): string;

package/dist/src/render.d.ts

@@ -1,6 +1,7 @@
 import type { BibliographyEntry } from "./types.js";
-export type RenderBibliographyInput = {
+type RenderBibliographyInput = {
     readonly title: string;
     readonly entries: readonly (readonly [string, BibliographyEntry])[];
 };
 export declare function renderBibliographyPage(input: RenderBibliographyInput): string;
+export {};

package/dist/src/state.d.ts

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

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@riebeckite/plugin-citations",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
+    "@riebeckite/core": "0.0.33",
     "@types/mdast": "^4.0.4",
-    "unist-util-visit": "^5.1.0",
-    "@riebeckite/core": "0.0.31"
+    "unist-util-visit": "^5.1.0"
   },
   "publishConfig": {
     "access": "public"