中文 README

Citation for SiYuan

A citation plugin that implements basic functionality, hoping to make your SiYuan more academically oriented.

Updates in 0.4.15

1. Redesigned database attribute synchronization settings with per-column built-in and custom mappings, including safe migration of legacy templates
2. Fixed refreshing all literature notes incorrectly processing nested documents; only direct children of the configured library are now refreshed
3. Improved single-select and multi-select attribute writes, template defaults, and handling of special characters

"In version 0.4.6, I made significant changes to the citation logic, which may cause some bugs. If you encounter any issues, please report them in time. Thank you very much!!!"

Important Updates in 0.4.0

1. Modified citation logic: adjacent citations should be edited together
2. Support for multiple citation styles
3. Compatibility with latest debug-bridge-1.0, updated communication details (backward compatible)
4. Support exporting Word documents and LaTeX with Zotero citations
5. Database synchronization support (template creation requires understanding of SiYuan's database)

Special thanks to Geo123abc for creating the tutorial video. Special thanks to Achuan-2 for creating the tutorial document

Features

Add citations to your notes, which refer to literature note generated in a specified folder, as shown in the following image:

Glossary

1. Notebook: Refers to a notebook in the SiYuan note document tree. The library can only be placed in one of the open notebooks. If you switch to another notebook for the library, the previously selected notebook's library will become invalid.
2. Database: The original data source of the literature, currently supports four types: data files (BibTeX and CSL-JSON), Zotero/Juris-M (using Better BibTeX plugin), Zotero/Juris-M (using debug-bridge plugin), and Zotero/Juris-M (using Web API). The data files are reimported every time the software is launched, but if the files themselves change during use, you need to "Reload the Database" (through the settings panel or command) or "Restart the SiYuan software" for the changes to take effect.
3. Library: The location where the inserted citation links point to the literature note. It is essentially a document located at a specific path. Its sub-documents are all literature note that has been referenced. The content of this document itself will not be modified, but it will be updated and refreshed when citations are inserted.
4. Literature Note Document: Generated documents based on the original data of the literature and the "Literature Note Template" set in the settings. The titles and names of newly created documents are set to the corresponding literature's citekey or itemKey. Currently, the content of this document refreshes every time the corresponding literature is referenced. Hence, please refrain from modifying the custom attribute 'literature-key' within the document properties. The literature content now supports a user data area, see Detailed Explanation of Literature Content, please avoid inserting personal content in non-user data areas.
5. Citation Link: The reference link inserted in the document (or copied to the clipboard), which points to the corresponding literature note in the library. The anchor text of the link is generated based on the literature's original data and the "Citation Link Template" filled in the settings panel.

Preparation before Use

Decide Which Literature Data Source to Choose

Currently, you can use four different sources for literature data: Data Files (BibTeX and CSL-JSON), Zotero/Juris-M (using Better BibTeX plugin), Zotero/Juris-M (using debug-bridge plugin), and Zotero/Juris-M (using Web API). The following table provides a comparison between the four data sources:

Data Source	BibTeX and CSL-JSON	Zotero/Juris-M with Better BibTeX plugin	Zotero/Juris-M with debug-bridge plugin	Zotero/Juris-M with Web API
Literature Identifier	citekey Allows multiple files Ensure uniqueness on your own	citekey Generated by BBT	citekey / itemKey citekey generated by BBT itemKey generated by Zotero	itemKey Generated by Zotero
Search Panel	Citation plugin panel	Zotero panel	Citation plugin panel / Zotero panel (optional)	Citation plugin panel
Initialization Speed	Slow	Fast	Fast	Fast
Search/Insert Speed	Fast	Slow	Fast (Citation plugin panel)	Fast
Compatible with Zotero 7	-	√	√	√
Compatible with Other Reference Managers	✓	×	×	×
Supports Importing PDF Annotations	×	×	✓	×
Support for Automatic Referencing from Zotero Drag-and-Drop	×	✓	✓	✓
Supports Inserting Multiple Literature at Once via Search Panel	×	✓	× (Citation plugin panel) ✓ (Zotero panel)	✓
Insert Zotero Selected Items	×	×	✓	✓
Insert Custom Tags into Zotero Items	×	×	✓	✓
Export to Word with Citations	×	×	✓	✓
Export to LaTeX with Citations	×	×	✓ (requires better-bibtex)	✓ (requires better-bibtex)

Configure the Plugin

1. Go to the settings panel: Click on the gear icon next to the Citation for SiYuan plugin switch in Settings - Marketplace - Downloaded to enter the settings panel. Alternatively, you can directly enter the plugin's settings panel by clicking on "Citation for SiYuan" in the plugin menu after clicking on the top toolbar's plugin button.
2. Select the notebook to store the literature note: Only notebooks that have been opened in the document tree can be selected from the drop-down list. If the previously selected notebook is not open in the current session, the plugin will be unable to function.
3. Fill in the library path: The path should start with /, for example, /References or /Assets/References. Note that this path is essentially the document's location, so do not include a trailing /. Note: If you change the path of the library, the literature libraries on the previous path will become invalid. Additionally, please ensure that the document exists, as the plugin does not automatically create the library document if it does not exist.
4. Choose Database Type: Select the type of database you want to use. If using data files, please refer to Using Data Files as Literature Data Source. If using Zotero/Juris-M (using Better BibTeX plugin), refer to Using Zotero/Juris-M (using Better BibTeX plugin) as Literature Data Source. If using Zotero/Juris-M (using debug-bridge plugin), refer to Using Zotero/Juris-M (using debug-bridge plugin) as Literature Data Source. If using Zotero/Juris-M (using Web API), refer to Using Zotero/Juris-M (using Web API) as Literature Data Source.
5. If you choose Zotero/Juris-M (using debug-bridge plugin) as the literature data source, it is recommended to enable the "Use Item Key as Index" option.
6. Fill in the template for the title of literature content documents: Enter the template for generating titles for literature content documents. For the specific syntax of the template, please refer to Template Syntax.
7. Fill in the literature note template: Fill in the template for generating the literature note document's text content. Refer to the section Template Syntax for specific template syntax.
8. If you believe you are an experienced user familiar with regular expression searching and SiYuan citation logic and want to be compatible with workflows outside of SiYuan, you can choose to enable the "Customize Citation Link" switch. For the specific effect of enabling this switch, refer to the section What Happens If I Enable the "Customize Citation Link" Switch?
9. Fill in the citation link template: Fill in the template for generating the anchor text of the citation link. Refer to the section Template Syntax for specific template syntax.
10. If you want to redesign your templates and data or want to see the default settings set by the plugin author, you can click the "Delete Data" button to delete all the saved settings data.
11. Choose whether to use dynamic anchor text for citation links (if the "Custom Citation" switch is also turned on, you will need to input a document naming template to customize the naming of literature note documents during insertion). Refer to Choosing Between Static and Dynamic Anchor Text for Citation Links for more details.
12. Settings information will be automatically saved after closing the settings panel.
13. Restart SiYuan (fully exit if in the system tray). If the settings are not taking effect after a restart or if there is a version mismatch after updating the plugin, restart one or two more times. This might help resolve issues, but some bugs might still exist.

If you have any doubts about this process, please refer to the tutorial video created by Geo123abc. If you still have questions, feel free to raise an issue on the plugin's GitHub repository or contact me via email (siyuan_citation@126.com)

If You Use BibTeX and CSL-JSON Files as the Literature Data Source

• Place any number of csl-json and bibtex files in the [Workspace]/data/storage/petal/siyuan-plugin-citation/references/ folder, which contain the literature you want to reference. Refer to How to Obtain Literature Data Files for methods to obtain the files.
• In the plugin's settings panel, select the "BibTeX and CSL-JSON" option for the database type.

If You Use Zotero/Juris-M (better-bibtex) as Literature Data Source

• Ensure that you have installed the Better BibTeX plugin in Zotero or Juris-M.
• In the plugin's settings panel, select Zotero (better-bibtex) or Juris-M (better-bibtex) as the database type.
• Make sure your Zotero or Juris-M is open before using the plugin.

If You Use Zotero/Juris-M (debug-bridge) as Literature Data Source

• Make sure you have installed the debug-bridge plugin in Zotero or Juris-M, and follow the Run Javascript in Zotero tutorial for configuration (you can choose not to use "CTT" as the password and set it in the settings panel accordingly).
• It is still recommended to install the Better BibTeX plugin in Zotero to automatically generate the citekey attribute for items.
• In the plugin's settings panel, select Zotero (debug-bridge) or Juris-M (debug-bridge) as the database type.
• In the "debug-bridge plugin" section of the settings panel, enter the password you set during configuration and select SiYuan (Citation plugin panel) or the Zotero panel as the search panel.
• Ensure that your Zotero or Juris-M is open before using the plugin.

If You Use Zotero/Juris-M (Web API) as Literature Data Source

• Make sure you are using Zotero 7 / Juris-M, enable Settings -> Advanced -> Allow other applications on this computer to communicate with Zotero, and ensure the local Web API is reachable. No Better BibTeX or debug-bridge plugin is required.
• In the plugin's settings panel, select Zotero (Web API) or Juris-M (Web API) as the database type.
• Web API mode always uses itemKey as the index. This mode is intended for users who want a simpler setup and do not want to install additional Zotero plugins.
• Ensure that your Zotero or Juris-M is open before using the plugin.
• Current scope:
  • Reading items, attachments, and notes is supported.
  • Basic attachment import works in the SiYuan desktop app.
  • PDF annotation support is currently limited; for the most complete annotation workflow, debug-bridge is still recommended.

Current Features

• Slash Menu:

  • Insert Literature Citation: Open the literature search panel, select the literature, and insert its citation link at the current cursor position, and update the literature library.

    You can access this option in the slash menu by typing "插入文献引用," "addcitation," or "charuwenxianyinyong."

  • Insert Literature Note: Open the literature search panel, select the literature, and insert its note at the current cursor position (this operation does not update the literature library). [Equivalent to copying the notes from Zotero/Juris-M and inserting them at the current cursor position]

    You can access this option in the slash menu by typing "插入文献笔记," "addliteraturenotes," or "charuwenxianbiji."

  • Cite Zotero Selected Items (debug-bridge plugin only): After selecting literature in Zotero, running this command will directly insert the selected (multiple) literature at the current cursor position.

  You can access this option in the slash menu by typing "引用Zotero中选中的文献," "addzoteroselecteditemscitations," or "yinyongzoterozhongxuanzhongdetiaomu."

• Commands (can be searched directly in the Top Bar Plugin Button - Command Panel or set shortcuts in Settings - Shortcuts - Plugins - Literature Reference):

  • Reload Database: Reload the database based on the source of the literature and re-index the literature library.
  • Insert Literature Citation: Open the literature search panel, select the literature, and insert its citation link at the current cursor position, and update the literature library. If not called by a shortcut key or the cursor is not focused in the editor, it will be copied to the clipboard instead.
  • Insert Literature Note: Open the literature search panel, select the literature, and insert its note at the current cursor position. If not called by a shortcut key or the cursor is not focused in the editor, it will be copied to the clipboard instead.
  • Cite Zotero Selected Items: Same function as in the Slash Menu. If not called by a shortcut key or the cursor is not focused in the editor, it will be copied to the clipboard instead.
  • Refresh All Literature Notes: Refresh the content of all literature note documents in the library. It's recommended to wait for a while before proceeding with the next action.
  • • Check Unlinked Literatures: Scans the Library to find and mark all literature entries that have lost their connection to a Zotero item.

• Document Title Block Menu:

  • Refresh Citations: Update all citation links in document using current template
  • Refresh Literature Note (only for library documents): Refresh current document's content
  • Refresh document title (only for library documents): Refresh the title of the current literature note document.
  • Export: Export documents with citations to:
    • Markdown with Zotero citations (requires BBT)
    • Word with citations
    • LaTeX with citations (requires BBT)
  • Bind to literature: Bind the current document to the selected literature. The content will be automatically treated as user data. If another document is already bound to the selected literature, they will be automatically merged.
  • Unbind from literature (only for library documents): Remove the binding from the selected literature. After this, all operations from this plugin will no longer affect this document.

• Citation Link Right-Click Menu:

  • Change Citation Style: Convert selected citation(s) to specified style

Template Syntax

How to write templates

• The template text syntax uses Markdown syntax.
• The parts to be replaced by variables are wrapped in {{ }}, for example {{title}}.
• In the input box of the Literature Content Template, you can use Shift/Ctrl + Enter to line break and use Tab to input tab characters.

In the templates for literature content and citations, the following variables can be used, and they are undefined by default if not present:

- {{key}}: Unique identifier of the literature, depending on whether "Use itemKey as Index" is enabled, it will be "libraryID_citekey" or "libraryID_itemKey," always exists.
- {{citekey}}: Identifier of the literature, requires ensuring uniqueness when using data files, automatically generated by the Better BibTeX plugin, if not installed, it will be the same as itemKey.
- {{itemKey}}: Unique identifier of the literature entry in Zotero, automatically generated by Zotero, does not exist if not using Zotero.
- {{libraryID}}: Library ID of the literature content in Zotero, defaults to 1 if using data files, and will support multiple libraries (multiple files with duplicate citekeys) in the future, does not exist if not using Zotero.
- {{abstract}}: Abstract.
- {{authorString}}: String of all authors sorted in order, empty string if not present.
- {{creators}}: Raw creator list (array of objects)
- {{firstCreator}}: First author
- {{containerTitle}}: Title of the publication (journal, conference proceedings, etc.) where the literature is located, null if not present.
- {{conferenceName}}: Conference name (only valid for conference papers).
- {{DOI}}: DOI of the literature.
- {{eprint}}: Eprint.
- {{eprinttype}}: Type of the eprint.
- {{eventPlace}}: Location of the event (e.g., conference).
- {{page}}: Page numbers.
- {{publisher}}: Publisher.
- {{publisherPlace}}: Place of publication.
- {{tags}}: All tags, connected with ", "; CSL-JSON files do not have this variable, empty string if not present.
- {{title}}: Title.
- {{titleShort}}: Abbreviated title, many literature entries do not have an abbreviated title.
- {{type}}: Type of the literature (note: the type identifier may be different when directly obtained from Zotero and when obtained after exporting).
- {{URL}}: URL of the literature.
- {{year}}: Publication year of the literature.
- {{files}}: Attachments of the literature. Will be displayed in the default format, one file per line, with a link to navigate to the file in Zotero (if it is a PDF, the link can directly open the PDF in Zotero).
- {{fileList}}: Attachments of the literature in the initial data source format, for user customization. It is an object list and can be accessed by using ".", empty list if not present. The method to call its attributes is as follows:
  - {{fileList[i].type}}: Type of the attachment, i.e., the file extension.
  - {{fileList[i].fileName}}: Complete file name of the attachment.
  - {{fileList[i].path}}: Absolute path of the attachment, with `file://`.
  - {{fileList[i].zoteroSelectURI}}: Link to select the attachment in Zotero (link only).
  - {{fileList[i].zoteroOpenURI}}: Link to directly open the attachment in Zotero (link only, for PDF files only).
- {{zoteroSelectURI}}: Directly navigate to the corresponding item in Zotero.
- {{note}}: Notes made in Zotero, supports direct navigation to Zotero through links.

Additionally, the following variables can be used in the citation links:

- {{shortAuthor}}: Generates a shorter author string according to the IEEE format (approximately), for example, "Lin and Morse et al.," empty string if not present.
- {{citeFileID}}: ID of the literature content document in SiYuan, used to assist in generating citation links or external links, for example, `20230707192208-ocs4482`.

The templates also include the following special variables:

• {{getNow}}: moment() object of the current time, allows customizing the format in the template, method reference moment.js.

If you use Zotero/Juris-M (debug-bridge) as the data source for literature, you can use the following variables:

- {{annotations}}: PDF annotations of the literature, distinguished by the document they belong to, also supports displaying annotations in batches, empty string if not present.
- {{annotationList}}: Initial data source format of PDF annotations, for user customization. It is an object list and can be accessed by using ".", empty list if not present. The method to call its attributes is as follows:
  - {{annotationList[i].parentKey}}: itemKey of the Zotero item where the annotation is located.
  - {{annotationList[i].parentTitle}}: Title of the PDF file where the annotation is located.
  - {{annotationList[i].detail}}: Details of single PDF file annotations, which is a list.
    - {{annotationList[i].detail[j].key}}: itemKey of the single annotation.
    - {{annotationList[i].detail[j].annotationText}}: Text content of the single annotation.
    - {{annotationList[i].detail[j].annotationComment}}: Comment of the single annotation.
    - {{annotationList[i].detail[j].annotationPosition}}: Position of the single annotation, you can use `.pageIndex` to obtain the page number of the annotation.
    - {{annotationList[i].detail[j].zoteroOpenURI}}: Link to directly open the location of the annotation in Zotero.

For more variables, check the "entry-data" attribute of the literature content document after importing, which includes all the information imported for that literature.

Advanced Template Syntax

In version 0.0.6, the template handling section utilizes template.js. To accommodate the template syntax commonly used by general users, before performing variable calculations and replacements, all {{ }} will be replaced with <%= %> for template.js to process the templates. Therefore, besides using the existing {{variable}} syntax, there are many advanced usage methods available:

1. Wrap JavaScript statements within {{ }}.
2. Use the native syntax of template.js (you can refer to the EJS syntax).

For example, the following template allows the line to not appear as "Tags: " when there are no {{tags}} variables:

{{ tags.length ? `\n**Tags**:\t\t${tags}` : "" }}

And the following template prevents the "Files" section from being generated when there are no associated files:

<% if (files.length) { %>
# Files

{{files}}
<% } %>

The following template has the same effect as the previous one:

<% if (fileList.length) { %>
# Files

{{fileList.map(file => {if (file.type === "pdf") return `[[Open]](${file.zoteroOpenURI})\t|\t[${file.fileName}](file.path)`; else return `[[Locate]](${file.zoteroSelectURI})\t|\t[${file.fileName}](file.path)`;}).join("\n")}}
<% } %>

Note: All variables return strings and will not directly return null. Therefore, please use .length to check if a variable exists.

Explaining Literature Note

In version v0.0.8, the literature note now supports a user data section, indicated by a top-level heading named "User Data" by default (this allows the floating preview in Obsidian to directly preview all user data). The content after this heading will not be updated with citations, but it also imposes some formatting requirements on the literature note. The format of an individual literature note document is as follows:

[User Data Title](siyuan://blocks/User Data Block ID)

Template-generated content

# User Data Title (default: "User Data")

User data content

What can be modified

• Everything below the # User Data Title (including the content of this heading) can be modified and will not be updated with citations.
• Anchored text can be added to the beginning citation, but it will not change with the user data title (it becomes static anchored text).

What cannot be modified

• The content above the # User Data Title, including the top-most citation, will be updated with citations, so please do not modify it.
• Do not delete the # User Data Title heading itself!! If you only clear its content, the block ID will not change. However, if you delete this heading and create a new one, the block ID will change, and all user data below it will be cleared in the next citation update!!!
• Do not delete the citation at the beginning of the document! If you delete this citation, the plugin will not be able to locate the user data section, and all content will be refreshed.

How to fix if the citation/heading has been deleted

• Add a heading at the top of the data you want to retain.
• Right-click on the heading, select "Copy," and choose "Copy as Block Reference." Paste it as the first line in the document.
• Ensure that only the reference link is present in the first line of the document.

How to Obtain BibTeX or CSL-JSON Files

• If you use Zotero:

  Use the Better BibTeX plugin to export your library in the format of Better BibLaTex or Better CSL JSON (select "Keep Update" to apply changes made to Zotero entries in SiYuan in real-time).

• If you use other reference management software:

  The sample.bib and sample.json files in [Workspace]/data/siyuan-plugin-citation/sample-data/ are provided for reference. If your software can provide exports in these formats, you can use them.

  Note: In the .bib and .json files, each literature's citekey/id must be unique.

Prerequisites for Web/Docker Version

Starting from version 0.3.6, the web and Docker versions can communicate with Zotero by installing the CORS Unblock extension in your browser. This enables frontend-browser communication with Zotero.

For Zotero/Juris-M (Web API) mode, the usable scope is:

• Best support: SiYuan desktop app with Zotero running on the same machine
• Possible: web/Docker deployment when the Zotero local API port is reachable from the browser or through the local network, and CORS is handled correctly
• Not guaranteed: mobile/browser-only environments that cannot directly access the Zotero local API port

In addition, some attachment import behavior in Web API mode relies on the desktop Node/Electron environment, so the desktop app currently provides the most complete experience.

What Happens If I Enable the "Customize Citation Link" Switch?

The citation link template will be fully customized, meaning that the template will no longer generate anchor text, but will be directly inserted into the document. In this case, to avoid affecting your own content, the refresh citation feature of the plugin will not maintain the non-link parts (outside the double brackets).

The regular expression for finding citation links is /\(\((.*?)\"(.*?)\"\)\)/g. Please make sure your template format conforms to this expression.

⚠️Note: After enabling the switch, please make sure your template includes ...(({{citeFileID}} "..."))..., otherwise the generated links will not be able to reference the literature note.

Choosing Between Static and Dynamic Anchor Text for Citation Links

This plugin strongly recommends using static anchor text for citation links (meaning the anchor text is enclosed in double quotes within the link and is not updated when the referenced document's name changes). This approach is not only more stable but also allows for the possibility of adding parameters to the citation links in future updates, allowing for different link formats (similar to \citep and \citet in LaTeX).

If dynamic anchor text for citation links is used, the document ID of the literature content will be temporarily displayed after referencing. The content will only appear after refreshing with F5.

What Happens When I Click the "Delete Data" Button?

Clicking the "Delete Data" button will delete all the data saved in the settings panel and restore it to the initial values set by the plugin author.

Note: This feature does not delete the .bib and .json files!

Using Databases for Literature Statistics

Starting from version 0.4.0, the Citation plugin can add literature documents to a SiYuan database and update database attributes while citing.

1. Enter the target database's Database Block ID.
2. Wait for the plugin to load its columns.
3. Choose a fill mode for each column. Select Do not fill for columns that the plugin should not maintain.

Built-in modes include:

• Select/multi-select: First author, Last author, and Journal;
• Date: Publication date;
• URL: URL and Zotero URL;
• Every column type: Custom.

Built-in modes safely handle empty values and JSON special characters. Legacy database attribute templates are migrated to per-column Custom settings only after the database columns load successfully. Columns absent from the legacy template remain disabled. If loading or migration fails, the original settings are preserved instead of being replaced with an empty configuration.

Custom Database Attributes

When Custom is selected, enter only that column's value object. Do not include keyID or the outer list. For example, a text column can use:

{
  "text": {
    "content": {{ JSON.stringify(title || "") }}
  }
}

A multi-select tag column can use:

{
  "mSelect": {{ JSON.stringify(tags ? tags.split(", ").map(content => ({ content })) : []) }}
}

Use JSON.stringify(...) for string output. Do not place {{ ... }} directly inside JSON quotes, because quotes, backslashes, or line breaks in literature metadata would produce invalid JSON.

The value structure for each column type is as follows:

Column Type	Value Structure
block	A block in the document. Do not write to this column.
number	{"number": {"content": <number>}}
text	{"text": {"content": "<string>"}}
select	{"mSelect": [{"content": "<single option value>"}]}
url	{"url": {"content": "<URL>"}}
mSelect	{"mSelect": [{"content": "<multi-select value 1>", "color": <option color>}, {"content": "<multi-select value 2>", "color": <option color>}, ... , {"content": "<multi-select value N>", "color": <option color>}]}
email	{"email": {"content": "<email address>"}}
phone	{"phone": {"content": "<phone number>"}}
checkbox	{"checkbox": {"content": {"checked": <true or false>}}}
date	{"date": {"content": "<date, Unix timestamp>", "content2": "<end date, Unix timestamp>", "isNotTime": <whether to show time, true/false>}}
mAsset	{"mAsset": [{"content": "<path to asset 1 in the data folder, usually starts with 'assets/'>", "name": "<name of asset 1>", "type": "<type of asset 1, currently 'image' or 'file'>"}, ... , {"content": "<path to asset N>", "name": "<name of asset N>", "type": "<type of asset N>"}]}

Extension: Indexing Literature documents in SiYuan from Zotero

Note: This feature is only available in debug-bridge plugin mode, as the transmitted data is itemKey, which cannot be obtained in other modes

Refer to the method in this forum, add the following to engine.json:

{
  "_name": "SiYuan",
  "_alias": "SiYuan",
  "_description": "Open Ref in SiYuan",
  "_icon": "https://b3log.org/siyuan/favicon.ico",
  "_hidden": false,
  "_urlTemplate": "siyuan://plugins/siyuan-plugin-citation/open-ref?key={z:key}",
  "_urlParams": [],
  "_urlNamespaces": {
    "z": "http://www.zotero.org/namespaces/openSearch#",
    "": "http://a9.com/-/spec/opensearch/1.1/"
  },
  "_iconSourceURI": "https://b3log.org/siyuan/favicon.ico"
}

Common Error Types

Please Select Notebook in Setting Tab

Please check if the notebook option in the settings panel is blank. The library must be located in an open notebook, otherwise, the plugin will not work. If the notebook where the library is located is closed, you need to reselect the notebook and path for the library.

Library Directory Does Not Exist

Please check if the library document exists. To prevent users from unintentionally disrupting their document hierarchy, the plugin does not automatically create a document in the document tree. When the library document does not exist, the plugin's functionality cannot be used.

After creating the document, you need to reload the database. Although it is not necessary, it is highly recommended restarting the SiYuan to ensure the effectiveness of setting.

Zotero/Juris-M Is Not Running

Please check the status of your Zotero/Juris-M and ensure that you have installed the Better BibTeX plugin in Zotero/Juris-M. This plugin relies on the Better BibTeX plugin to run. There are plans to directly access zotero.sqlite without relying on this plugin in the future.

All These Problems Are Not Included

It is welcomed to raise an issue

TODO

• Support citation of formulas
• Support adding LaTeX definition blocks such as Remark, Lemma
  • Adaptation for mobile devices

Developers

This plugin exposes specific events for external calls. Here's how you can utilize them:

1. Get the eventBus object of this plugin under window.siyuan.ws.app.plugins

   window.siyuan.ws.app.plugins.find(p => p.name === "siyuan-plugin-citation").eventBus

2. Use eventBus.emit(rule: TRuleType, e: CustomEventDetail) to send requests

  type TRuleType = "GetFromPool" | "Refresh";
  interface RefreshEventDetail extends CustomEventDetail {
    type: "database" | "literature note";
    docIDs?: string[];
    keys?: string[];
    refreshAll?: boolean;
    confirmUserData?: boolean;
  }

  interface GetEventDetail extends CustomEventDetail {
    keyorid: string;
    triggerFn: (idorkey: string) => any;
  }

• For the GetFromPool rule, the parameter e has a type of GetEventDetail.
• For the Refresh rule, the parameter e has a type of RefreshEventDetail. Use the type to choose whether to reload the database or refresh literature content. Set confirmUserData to false to avoid displaying the "User data not found" prompt.

Acknowledgments

The code of the following projects was referenced, and I would like to express my gratitude:

sy-transfer-refs

obsidian-citation-plugin

siyuan-plugin-importer

obsidian-zotero-integration

template.js

siyuan-package-monorepo

Thanks to everyone in the "思源笔记折腾群" for answering my questions and providing guidance.

Thanks to Geo123abc and ttChen for providing information, suggestions, and testing support.

Sponsorship

I actually prefer GitHub issues over sponsorship. Every question and request you raise there becomes my motivation.