已经实现了基本功能的引用插件,从这里开始将思源变得更加学术
0.3.6更新:
- 开放了docker和远程网页版的使用,通过在浏览器上安装CORS Unblock 插件可以使用浏览器前端与zotero通信。
- 转变用户数据的引用模式为思源链接,不会再占用反链,并且用户数据标识由判断开头的引用变为用户数据标题的自定义属性。
- 感兴趣的用户可以自行编译尝试dev分支下的代码,目前的新功能主要推送到这里,但是前端还不是很完善。
- 对于下载了最新的debug-bridge插件的用户,请在zotero的
编辑->设置->高级->编辑器
中设置extensions.zotero.debug-bridge.token
为您的密码,并更新到最新版的citation插件,即可正常使用。
在0.1.1坂本中,本插件已经支持通过debug-brige插件访问Zotero的功能,相对于现在版本使用better-bibtex的方法,这种方式的访问速度更快,效率更高,并且可以实现很多额外的功能(详见大佬的quicker动作,在思源或者zotero上的功能之后都有可能实装在该插件中),使用该功能的用户需要提前做好准备,具体的准备方法参考Run Javascript in Zotero
在笔记中添加文献引用,该引用指向在你指定的文件夹下生成的文献内容,如下图所示:
- 笔记本:即思源笔记文档树中的笔记本,文献库只能放置在其中一个已经打开的笔记本中,如果切换文献库所在笔记本那么原本笔记本中的文献库将失效。
- 数据库:文献的原始数据来源,目前支持数据文件(BibTex和CSL-JSON)、Zotero/Juris-M(使用better-bibtex插件)和Zotero/Juris-M(使用debug-bridge插件)三种数据来源。其中数据文件在每次启动软件时都会重新导入,但是如果在使用中文件本身产生变化,需要【重新载入数据库】(通过设置面板或命令)或者【重启思源软件】才能生效。
- 文献库:存放已经插入引用连接的文献内容的位置,本质上是一个处于特定路径的文档,它的子文档为所有引用过的文献内容,该文档本身的内容不会被修改,但是在插入引用时会增添和刷新它的子文档。
- 文献内容:根据文献的原始数据和设置界面填写的“文献内容模板”生成的文档,新建文档的标题和命名为该文献的citekey或者itemKey。目前该文档的内容在每次引用对应文献时都会刷新,因此 请不要在文档属性修改自定义属性literature-key,目前文献内容已经支持用户数据区域,详见文献内容详解,非用户数据区域请不要填入个人内容。
- 引用链接:在文档中插入(也可以选择直接复制到剪贴板)的引用链接,该链接指向文献库中对应的文献内容,其锚文本为通过文献原始数据和设置界面填写的“引用模板”生成的文本。
目前可以使用的文献数据来源包括数据文件(BibTex和CSL-JSON)、Zotero/Juris-M(使用better-bibtex插件)和Zotero/Juris-M(使debug-bridge插件)三种,下表给出了三种数据来源之间的对比:
数据来源 | BibTex和CSL-JSON | Zotero/Juris-M 使用better-bibtex插件 |
Zotero/Juris-M 使用debug-bridge插件 |
---|---|---|---|
文献标识 | citekey 允许多个文件 自行保证唯一性 |
citekey 由BBT生成 |
citekey / itemKey citekey由BBT生成 itemKey由Zotero生成 |
搜索面板 | Citation插件面板 | Zotero面板 | Citation插件面板 / Zotero面板 (可选) |
初始化速度 | 慢 | 快 | 快 |
搜索/插入速度 | 快 | 慢 | 快(Citation插件面板) |
兼容Zotero 7 | - | × (暂时) | √ |
兼容其它文献管理软件 | ✓ | × | × |
支持导入pdf标注 (annotations) |
× | × | ✓ |
支持从Zotero拖入选中/批注时自动引用 | × | ✓ | ✓ |
支持通过搜索面板 一次性插入多篇文献 |
× | ✓ | ×(Citation插件面板) ✓ (Zotero面板) |
插入在Zotero中 选中的条目 |
× | × | ✓ |
支持在Zotero条目中 插入跳转思源链接 |
× | × | ✓ |
支持在Zotero条目中 插入自定义标签 |
× | × | ✓ |
生成带有引用的word文档 (未来版本) |
× | ✓ | ✓ |
- 进入设置界面:点击
设置-集市-已下载-文献引用
插件开关旁边的齿轮按钮进入设置界面,也可以通过在顶栏插件按钮点击后的菜单中点击文献引用
直接进入插件的设置界面。 - 选择存放文献内容的笔记本:只能下拉选择已经在文档树中打开的笔记本,如果之前设置的笔记本本次启动未打开,那么将无法使用本插件。
- 填写文献库路径:路径以
/
开头,例如/References
或者/Assets/References
,注意该路径本质上为文档所在路径,不要在最后加/
。注意:如果更换了文献库的路径,之前路径上的文献库将失效。此外,请确保该文档存在,因为本插件不会自动创建文献库文档 - 选择数据库类型:选择使用的数据库的类型,如果使用数据文件请参考使用数据文件作为文献数据来源,如果使用Zotero/Juris-M(使用better-bibtex插件)请参考使用Zotero/Juris-M(使用better-bibtex插件)作为文献数据来源,如果使用Zotero/Juris-M(使用better-bibtex插件)请参考使用Zotero/Juris-M(使用debug-bridge插件)作为文献数据来源。
- 如果你选择Zotero/Juris-M(使debug-bridge插件)作为文献数据来源,推荐开启“使用itemKey作为索引”选项
- 填写[文献内容文档标题]模板:填写生成文献内容文档的标题模板,模板的具体写法参考模板写法。
- 填写文献内容模板:填写生成文献内容文档的文本内容模板,模板的具体写法参考模板写法。
- 如果你认为你是对正则表达式查找和思源引用逻辑有了解的资深用户,并且想要兼容思源外的工作流,可以选择打开
自定义引用
的开关,打开该开关的具体效果详见如果我打开了“自定义引用”的开关 - 填写引用链接模板:填写生成引用链接锚文本的模板,模板的具体写法参考模板写法。
- 如果你希望重新设计你的模板和数据,或者希望看到插件作者设置的默认设置,可以通过删除数据按钮将保存的设置数据全部删除。
- 选择是否使用动态锚文本的引用链接(如果还打开了“自定义引用”的开关,则还需要输入文档命名模板,以便在插入时自定义文献内容文档的命名),详细参考引用链接该使用静态锚文本还是动态锚文本
- 关闭设置面板后设置信息会自动保存。
- 重启思源笔记(如果是在托盘区,也要完全退出来),重启之后如果设置没有生效,或者更新插件之后版本不对,请再次重启一至两次,有可能可以解决,但是目前不排除还有bug。
如果对这个过程仍然有疑惑,请参考Geo123abc制作的教学视频。如果仍然无法解答您的疑惑,欢迎到本插件的github仓库上提issue或者将问题发送到我的邮箱(siyuan_citation@126.com)
- 在
[工作空间]/data/storage/petal/siyuan-plugin-citation/references/
文件夹下,放置任意数量的csl-json
和bibtex
文件,其中包含你所想要引用的文献,文件的获取方法参考如何获得文献数据文件。 - 在插件的设置面板中,数据库类型处选择
BibTex and CSL-JSON
。
- 确保你的 Zotero 或者 Juris-M 中安装了 Better BibTex 插件。
- 在插件的设置面板中,数据库类型处选择
Zotero (better-bibtex)
或者Juris-M (better-bibtex)
。 - 在使用前确保你的 Zotero 或者 Juris-M 是打开的。
- 确保你的 Zotero 或者 Juris-M 中安装了 debug-bridge 插件,并按照 Run Javascript in Zotero 教程进行配置(可以不选择“CTT”作为密码,只需要在设置面板中进行相应设置)
- 仍然推荐在Zotero中安装Better BibTex插件,以自动生成条目的citekey属性。
- 在插件的设置面板中,数据库类型处选择
Zotero (debug-bridge)
或者Juris-M (debug-bridge)
。 - 在设置面板的“debug-bridge插件”栏中,输入设置时配置的密码,并选择使用SiYuan(Citation插件面板)或者Zotero面板作为搜索面板。
- 在使用前确保你的 Zotero 或者 Juris-M 是打开的。
-
斜杠菜单:
-
插入文献引用:弹出文献搜索面板,选中文献后在光标位置插入该文献的引用链接,并更新文献库。
通过输入“插入文献引用”、“addcitation”、“charuwenxianyinyong”都可以在斜杠菜单中索引到这个选项
-
插入文献笔记:弹出文献搜索面板,选中文献后在光标位置插入该文献的笔记(该操作不更新文献库)。【相当于将Zotero/Juris-M中的笔记复制并插入到当前光标位置】
通过输入“插入文献笔记”、“addliteraturenotes”、“charuwenxianbiji”都可以在斜杠菜单中索引到这个选项
-
引用Zotero中选中的文献(仅debug-bridge插件可用):在Zotero中选中文献后,运行该命令则可直接将选中的(多个)文献插入到当前光标位置。
通过输入"引用Zotero中选中的条目"、"addzoteroselecteditemscitations"、"yinyongzoterozhongxuanzhongdetiaomu"都可以在斜杠菜单中索引到这个选项。
-
-
命令(可以在
顶栏插件按钮-命令面板
直接搜索选中,或者在设置-快捷键-插件-文献引用
中设置快捷键使用): -
文档右上角“更多”菜单:
-
模板文本语法使用的是 Markdown 语法。
-
想要被变量替换的部分用
{{ }}
包裹,例如{{title}}
。 -
在文献内容模板输入框中可以使用
Shift/Ctrl + Enter
换行,和用Tab
输入制表符。
在文献内容和引用的模板中可以使用如下变量,默认不存在时为undefined
:
- {{key}}:文献的唯一标识,根据“使用itemKey作为索引”选项开启的不同为“libraryID_citekey”,或者“libraryID_itemKey”,必定存在。
- {{citekey}}:文献的标识,使用数据文件需要自行保证唯一性,使用better bibtex插件会自动生成,如果没有安装bbt插件则与itemKey相同
- {{itemKey}}:文献条目在Zotero中的唯一标识,由Zotero自动生成,不使用Zotero则不存在
- {{libraryID}}:文献内容在Zotero中的库ID,如果使用数据文件则默认为1,未来将据此支持多个库(多个文件可重复citekey)的搜索插入,不使用Zotero则不存在
- {{abstract}}:摘要
- {{authorString}}:所有作者按顺序排列的字符串,不存在则为空字符串
- {{containerTitle}}:文献所在刊物(论文集、期刊等)标题,不存在则为null
- {{DOI}}:文献的 DOI
- {{eprint}}:预印本
- {{eprinttype}}:预印本类型
- {{eventPlace}}:(会议等)地点
- {{page}}:页码
- {{publisher}}:出版商
- {{publisherPlace}}:出版商所在地
- {{tags}}: 所有的标签,以", "连接, CSL-JSON 文件中没有此变量,不存在则为空字符串
- {{title}}:标题
- {{titleShort}}:简写标题,很多文献不存在简写标题
- {{type}}:文献的类型(注意:直接从 zotero 获取的和导出后再获取的文献类型标识可能不一样)
- {{URL}}:文献的访问网址
- {{year}}:文献的发表年份
- {{files}}:文献的附件。会直接显示默认样式,每行一个文件,并附带跳转到 zotero 的链接(如果是 pdf 则链接可以直接在 zotero 中打开 pdf 。
- {{fileList}}:文献的附件,为初始数据源格式,方便用户自定义。本身是一个对象列表,可以通过`.`调用其属性,不存在则为空列表。具体属性的调用方法如下:
- {{fileList[i].type}}:附件的类型,即文件扩展名
- {{fileList[i].fileName}}:附件的完整文件名
- {{fileList[i].path}}:附件的绝对路径,带有`file://`
- {{fileList[i].zoteroSelectURI}}:在 Zotero 中能够选中附件的链接(仅链接)
- {{fileList[i].zoteroOpenURI}}:在 Zotero 中能够直接打开附件的链接(仅链接,仅pdf文件)
- {{zoteroSelectURI}}:可以直接跳转到Zotero对应的条目
- {{note}}:在Zotero中做的笔记,其中的链接支持直接跳转到Zotero
此外,在引用链接中还可以使用下面的变量:
- {{shortAuthor}}:按照IEEE格式(大概)生成较短的作者字符串,例如`Lin and Morse et al.`,不存在则为空字符串
- {{citeFileID}}:文献内容文档在思源内部的ID,用于辅助生成引用链接或者外链,例如 `20230707192208-ocs4482`
模板中还包含以下特殊变量:
- {{getNow}}:当前时间的
moment()
对象,可以在模板中自定义格式,方法参考moment.js。
如果你使用 Zotero/Juris-M (debug-bridge) 作为文献数据来源,则可使用下面的变量:
- {{annotations}}:文献的pdf标注,将按所属的文档区分,同样支持批注的展示,不存在则为空字符串。
- {{annotationList}}:pdf批注的初始数据源格式,方便用户自定义。本身是一个对象列表,可以通过`.`调用其属性,不存在则为空列表。具体属性的调用方法如下:
- {{annotationList[i].parentKey}}:标注所在pdf条目的itemKey
- {{annotationList[i].parentTitle}}:标注所在pdf文件的标题
- {{annotationList[i].detail}}:单个pdf文件标注的细节,是一个列表
- {{annotationList[i].detail[j].key}}:单个标注的itemKey
- {{annotationList[i].detail[j].annotationText}}:单个标注的文本内容
- {{annotationList[i].detail[j].annotationComment}}:单个标注的批注
- {{annotationList[i].detail[j].annotationPosition}}:单个标注的位置,可以用`.pageIndex`获得标注的页码
- {{annotationList[i].detail[j].zoteroOpenURI}}:直接在Zotero中打开标注位置的链接
更多的变量可以在导入文献后查看文献内容文档的“entry-data”属性,其中包含了导入的所有该文献信息。
在0.0.6版本中,模板处理部分使用了template.js,为了适配一般用户的模板语法,在进行变量计算和替换之前,会将所有的{{ }}
替换为<%= %>
以供 template.js 进行模板处理。因此,除了使用旧有的{{变量}}
语法外,还可以有很多高级的使用方法:
- 在
{{ }}
中包裹JavaScript
语句 - 使用 template.js 原生语法(可以参考 EJS 语法)
例如如下模板,就可以在条目没有变量{{tags}}
时让本行不出现**Tags**:
:
{{ tags.length ? `\n**Tags**:\t\t${tags}` : "" }}
而如下模板能够让 Files 这一栏在没有附属的文件时不在生成:
<% if (files.length) { %>
# Files
{{files}}
<% } %>
这一段模板和下面这一段模板有同样效果:
<% 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")}}
<% } %>
**注意:**所有变量返回的都是字符串,而不会直接返回null
,所以请根据.length
判断变量是否存在。
在v0.0.8版本中,文献内容支持了用户数据区域,其标志是默认名为User Data
的一级标题(以便思源的悬浮预览能够直接预览到所有的用户数据),在这个标题之后的部分不会随着引用更新,但是由此也对文献内容的格式产生了一些要求。现在单个文献的文献内容文档格式如下:
((用户数据标题ID '用户数据标题'))
模板生成内容
# 用户数据标题(默认为“User Data”)
用户数据内容
- 全部在
# 用户数据标题
下方(包括该标题的内容)都是可以进行修改的,不会随着文献引用而更新。 - 文档开头的引用可以添加锚文本,但是此时它将不会随用户数据标题变化(转变为静态锚文本)。
- 在
# 用户数据标题
上方的部分,是会随着文献引用而更新的(包括最上方的引用),因此请不要修改。 - 不要删除
# 用户数据标题
这个标题本身!! 如果仅仅是清空其内容,块ID是不会变化的,但是如果将这个标题删除之后再新建,块ID会产生变化,进而在下次引用中会清空所有下方的用户数据!!! - 不要删除文档开头的引用! 如果删除该引用,插件将找不到用户数据区域,此时全部内容将刷新。
- 在想要保留的数据的最上方加入标题。
右键标题-复制-复制为引用块
,粘贴在文档的第一行。- 确保文档第一行中只有该引用链接
-
如果你使用
Zotero
:使用
Better BibLatex
插件,以Better BibLaTex
或者Better CSL JSON
的格式导出文献库(同时可以选择Keep Update
以便在修改Zotero中的条目后能够及时应用在思源中) -
如果你使用的其它文献管理软件:
在
[工作空间]/data/siyuan-plugin-citation/sample-data/
中提供了sample.bib
和sample.json
用于参考,如果你使用的软件能够提供这样的导出,那么就可以使用注意!在
.bib
和.json
文件中,每个文献的citekey/id
必须是唯一的
引用链接模板将变为完全自定义引用的格式,即引用链接模板生成的内容不再为锚文本,而是将直接插入文档。此时,为了避免对用户自身内容的影响,插件的刷新引用功能将不会对链接(即双括号)外的部分进行维护。
查找引用链接的正则表达式为 /\(\((.*?)\"(.*?)\"\)\)/g ,请据此把握好您的模板格式
...(({{citeFileID}} "..."))...
否则生成的链接将无法引用
本插件强烈建议用户使用静态锚文本的引用链接(即链接中包裹锚文本的是双引号,并且锚文本不随被引用文档的命名更新而更新),不仅是因为静态锚文本相对来说更加稳定,而且在此后的功能追加中,可能会给引用链接添加参数,即可以区分该链接的格式(类似于LATEX中的\citep和\citet)。
如果使用动态锚文本的引用链接,引用后会暂时显示文献内容的文档id,使用F5
刷新之后才会显示文档。
“删除数据”按钮会将设置界面填写保存的所有数据都删除,并将其还原为插件作者所设置的初始值。
注意:该功能不会导致.bib
和.json
文件被删除!
请检查设置面板中笔记本选项是否为空白。文献库必须位于已经打开的笔记本中,否则本插件将无法使用。如果文献库所在的笔记本被关闭,则需要重新设定文献库所在笔记本和路径。
请检查文献库文档是否存在。由于不希望用户在无意间打乱自身的文档层级安排,因此本插件不会自动在文档树中新建文档,当文献库文档不存在时,将无法使用本插件的功能。
新建相关文档之后,需要重新载入数据库。虽然理论上没有必要,但是强烈建议重新启动思源笔记,以保证文献库路径生效
请检查您的 Zotero/Juris-M 的打开状态,以及在 Zotero/Juris-M 中是否安装了 Better BibTex 插件,本插件依赖于该插件运行,目前有不依赖该插件直接访问zotero.sqlite的计划。
欢迎到本插件的github仓库上提issue或者将问题发送到我的邮箱(siyuan_citation@126.com)
- Zotero 集成
长期
- 支持文献内容中的用户自定义片段
大概下个版本
- 支持复制出带有引用的markdown文本
大概下个版本
- 支持直接访问zotero.sqlite, 参考obsidian-zotero
长期(真的很难)
- 导出支持Word
长期
- 导出支持 LATEX
长期
- 支持公式引用和自动编号
长期
- 支持添加 Remark, Lemma 等 LATEX 定义块
长期
- 美化界面
脑子要炸
- 功能优化:
- 更宽松的模板/路径格式限制
多给我提issue
- 更好的 Template 处理
好难写
- 命令面板中去掉无效功能
等V姐更新
- 支持 citation link 中使用 index
等V姐更新
- 适配移动端
有没有大哥先试试
- 更宽松的模板/路径格式限制
本插件对外暴露特定的Event以供外部调用。调用方法如下:
- 获取
window.siyuan.ws.app.plugins
下本插件的eventBus
对象
window.siyuan.ws.app.plugins.find(p => p.name === "siyuan-plugin-citation").eventBus
2. 使用eventBus.emit(rule: TRuleType, e: CustomEventDetail)
来发送请求
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;
}
GetFromPool
对应的参数e的类型为GetEventDetail
Refresh
对应的参数e的类型为RefreshEventDetail
,通过type
选择重新载入数据库或者刷新文献内容,confirmUserData
设置为false
可以不弹出“未找到用户数据”的提示
参考了以下项目的代码,非常感谢
感谢 “思源笔记折腾群”的大伙给我答疑解惑 感谢Geo123abc和ttChen提供的资料和参考建议,以及相关的测试支持
比起赞助,其实更喜欢在github上的issue,你提的每一个问题和需求都会成为我的动力