引用

可以说，这个模板最重要的特性是它能够从简单的标识符自动生成引用。这使得引用和维护大量的出版物列表变得容易。

该模板之所以能够做到这一点，要归功于 Manubot，这是一套工具，（除其他功能外）允许您仅通过一个简短的标识符（如 doi、url、isbn、pmc、pmcid、pubmed、arxiv 以及更多）自动生成包含完整详细信息的引用。

工作原理

首先，让我们定义一些一致的术语，以便更容易解释：

来源 (source) - 您想要引用的论文、书籍、文章、网页、电影或任何其他已发表的项目。
元来源 (metasource) - 列出多个来源的单个项目，例如作者的 ORCID 号码可用于获取其已发表作品的列表。
引用 (citation) - 关于来源的完整、详细信息，如标题、作者、出版商、出版日期、URL 等。

对于您网站上的大多数内容，您只需更改相应文件的内容即可。引用有一个特殊的附加步骤。当您添加新的来源或元来源进行引用时，模板必须运行一个特殊的“引用处理”过程来生成您的完整引用。

从高层次来看，其工作原理如下：

mermaid

%%{
  init: {
    "fontFamily": "Arial",
    "stroke": "none",
    "flowchart": {
      "curve": "monotoneX"
    }
  }
}%%

graph LR
  subgraph 输入
    sources([sources*.yaml])

    subgraph 元来源
      orcid([orcid*.yaml])
      etc([等等...])
    end
  end

  subgraph 引用处理
    expand([扩展为来源])
    merge([合并来源])
    manubot([Manubot])
    preserve([保留输入字段])
  end

  subgraph 输出
    citations([citations.yaml])
    title[标题, 作者, 等...
输入字段]
  end

  subgraph 网站
    display[引用组件
列表组件]
  end

  sources --> merge
  orcid --> expand
  etc --> expand
  expand --> merge
  merge --> manubot
  manubot --> preserve
  preserve --> citations
  citations --> display

  classDef node fill:#38bdf8,stroke:none,color:white
  classDef cluster fill:#e0f2fe,stroke:white,stroke-width:3px
  classDef input fill:#e0f2fe
  classDef cite fill:#ffedd5
  classDef output fill:#dcfce7
  classDef title fill:none,color:black
  class input, input
  class cite, cite
  class output, output
  class title, title
  class display, title

在 /_data 文件中输入您的来源和元来源，例如 sources-2020.yaml、orcid-students.yaml 等。
引用处理过程运行——无论是在 GitHub 上还是本地——将您的来源和元来源转换为完整的引用。
引用处理过程在 /_data 中输出一个单独的 citations.yaml 文件。
使用列表和引用组件在您的网站上显示和筛选引用。

提示

不要编辑 citations.yaml！每次引用处理过程运行时，它都会被覆盖。如果您需要手动输入或更正内容，请参见下文。

引用处理过程详解...

每个来源/元来源文件根据文件名前缀由相应的引用插件（参见 /_cite/plugins）处理。
在元来源文件中，每个列表条目都会扩展为常规来源列表。您在原始条目中放入的任何字段都会复制到扩展列表中的每个来源。
在来源文件中，每个列表条目保持原样。
关于引用处理过程的元数据会附加到每个来源上，例如它源自哪个输入文件以及使用了哪个引用插件运行。
编译一个完整的常规来源列表，重复的来源通过 id 合并。
合并两个条目时，如果同一字段同时存在于两者中，则完整列表中较晚出现的条目会覆盖较早出现的条目（因为字典/对象中不能有两个同名的键）。
Manubot 为每个具有 id 的来源生成完整的引用详细信息。
每个来源上最初存在的任何字段都会被保留。

您可以混合搭配任意数量的来源和元来源，并以任何方式在任何地方显示它们！例如，您可能希望有一个“CV”页面，列出您 PI（首席研究员）ORCID 下的所有论文，然后将“研究”页面保留给您实验室中不同成员撰写的几篇您想要重点介绍的特殊论文。

示例

基本 ID

文件名必须以 sources 开头。

yaml:/_data/sources.yaml

- id: doi:10.1098/rsif.2017.0387
- id: pubmed:29424689
- id: pmc:PMC5640425
- id: arxiv:1806.05726
# ...更多来源

参数	描述
`id`	来源的标识符，Manubot 可以理解并引用。如果 Manubot 无法为此 ID 生成引用，模板将记录错误消息并以错误代码退出。

丰富细节

或者，您可以手动传递额外的“丰富”细节，模板可以很好地显示这些细节。Manubot 无法自动确定这些。

yaml:/_data/sources.yaml

- id: arxiv:1806.05726
  type: paper
  description: 这是一些 _示例_ 描述。
  image: https://publisher.com/striking-image-for-your-paper.jpg
  buttons:
    - type: source
      link: https://github.com/your-lab/some-repo
    - type: website
      text: 我的个人网站
      link: http://some-website.com/
  tags:
    - 生物学
    - 大数据
    - 医学
  repo: your-lab/some-repo

# ...另一个来源

参数	描述
`type`	来源的类型。决定要显示的图标。请参阅 `/_data/types.yaml` 查看内置类型或添加您自己的类型。
`description`	来源的简要描述。可以包含 Markdown。
`image`	来源的醒目图像 URL。强烈推荐。显示为引用详细信息旁边的缩略图。
`buttons`	显示在引用详细信息下方的按钮列表。
`tags`	显示在引用详细信息下方的标签列表。
`repo`	GitHub 仓库，用于自动获取额外的标签。

提示

始终为您的出版物提供一个好的缩略图。使用来源中的插图，如果没有，则使用期刊徽标或期刊封面。这里有一些制作好的缩略图的最佳实践。

手动覆盖

您附加到来源（或元来源，见下文）的所有字段都会原封不动地传递到生成的引用中。这允许您手动输入或更正引用的详细信息。

yaml:/_data/sources.yaml

# 手动更正特定的引用细节
- id: pmc:PMC5640425
  publisher: Cold Spring Harbor

# 手动提供所有引用细节
- title: 某个出版物标题
  authors:
    - "**史蒂夫·麦奎因**"
    - 闪电麦昆
  publisher: bioRxiv
  date: 2021-01-01
  link: biorxiv.org/1234

# 附加一个任意字段
- id: pmc:PMC5640425
  some-field: 123

参数	描述
`title` / `authors` / `publisher` / `date` / `link`	基本引用信息，通常由 Manubot 返回并由引用组件显示。日期应为 `YYYY-MM-DD` 格式。作者可以包含 Markdown。

如果您不提供 id，Manubot 就没有可引用的内容，因此不会运行。只有在手动提供所有引用详细信息时才需要这样做。这违背了模板的主要优势，但有时是必要的。

您还可以附加任意字段。模板不会显式使用它们，但您可以使用它们通过列表组件筛选引用。

ORCID

ORCID 是检索作者完整已发表作品集的推荐方法。

文件名必须以 orcid 开头。

yaml:/_data/orcid.yaml

- orcid: 0000-0002-4655-3773
  jane-doe: true

# ...另一位作者

每个 ORCID 都会扩展为包含 id 的完整常规来源列表。您在原始条目中放入的任何字段都会复制到扩展列表中的每个来源。这也适用于下面其他类型的元来源。

为了方便、明确地将 ORCID 与某个人关联起来以便使用列表组件进行筛选，您可以像上面的示例一样为该人添加一个唯一字段，并使用如下过滤器：

liquid

{% raw %}
{% include list.html data="citations" component="citation" filters="jane-doe: true" %}
{% endraw %}

为什么这样设置过滤器？

为什么让唯一作者作为键（例如 jane-doe: true）而不是值（例如 member: jane-doe）？如果执行后者，并且同一个人是同一来源的作者，则只会保留其中一位作者（以最后列出的为准）。这是本页其他地方描述的行为的结果（重复的来源合并为一个，字典/对象上不能有重复的键）。

因为引用处理过程通过 id 合并重复的来源，您也可以使用上面的手动覆盖方法来手动更正从元来源返回的来源。您还可以使用特殊的 remove 字段来忽略从元来源返回的来源，将其从引用输出中丢弃。示例：

yaml:/_data/sources.yaml

# 某个由 ORCID 返回但标题错误的论文
- id: doi:123/456
  title: 正确的标题

# 某个由 ORCID 返回但您根本不想保留的论文
- id: pubmed:123456
  remove: true

提示

如果元来源返回的来源标识符类型 Manubot 不知道如何引用，则该来源将被忽略。发生这种情况时，引用处理过程会打印一个警告，而不是严重错误，因此您需要检查您的 CLI 输出或 GitHub Actions 日志。

PubMed

有关常规元来源功能，请参见上面的 ORCID 部分。

使用 NCBI eutils 在 PubMed 中搜索术语。这是一种选择作者论文的脆弱方法，非常容易出现误报。推荐使用 ORCID。

文件名必须以 pubmed 开头。

yaml:/_data/pubmed.yaml

- term: "Greene, C[Author] NOT Greene CE[Author]"

Google Scholar

有关常规元来源功能，请参见上面的 ORCID 部分。

不幸的是，Google 没有为其许多服务提供 API，其中就包括 Scholar。幸运的是，有一个第三方 API 可以访问它，即 SerpAPI。首先，您需要注册并获取 API 密钥。然后，如果在 GitHub 上运行引用处理过程，请创建一个名为 GOOGLE_SCHOLAR_API_KEY 的新的仓库机密，其值为您的 API 密钥；或者，如果在本地运行，请将相同的名称/值放入 .env 文件中。

文件名必须以 google-scholar 开头。

yaml:/_data/google-scholar.yaml

- gsid: ETJoidYAAAAJ

定期更新

像 ORCID 这样的元来源会随着您发表新来源而随时间更新。为了适应这种情况，模板会尝试定期自动重新运行引用处理过程。在您的仓库的“▶️ Actions”中，查看“on schedule”工作流。

提示

GitHub 对计划的工作流施加了某些限制。您可能需要手动启用工作流，或者过一段时间后重新启用它。

当工作流运行时，它将获取与您的元来源关联的最新来源，像往常一样生成引用，并打开一个拉取请求，让您在发布更改之前进行审查。

提示

由于另一个 GitHub 限制，如果您想查看此拉取请求的实时预览链接，您需要关闭（不是合并）并重新打开它。这应该会触发“构建预览”工作流。

缓存

如果您有很多来源，为所有来源生成引用可能需要一些时间。为了节省时间，引用处理过程为 Manubot/ORCID/等网络请求维护了一个生存时间缓存。如果缓存的响应尚未过期，则使用它而不是发出新请求。要清除此缓存，只需删除缓存目录 _cite/.cache。您还可以在 _cite 中的 Python 代码中自定义默认过期时间。

引用 ​

工作原理 ​

示例 ​

基本 ID ​

丰富细节 ​

手动覆盖 ​

ORCID ​

PubMed ​

Google Scholar ​

定期更新 ​

缓存 ​

引用

工作原理

示例

基本 ID

丰富细节

手动覆盖

ORCID

PubMed

Google Scholar

定期更新

缓存