# 引用與參考文獻

尋找來源、檢視其中繼資料、將它加入正確的參考文獻檔案、在游標處引用、選擇 Typst 引用樣式，並整理文獻庫而不失去原始內容。

引用是一條鏈：論點指向一個鍵，鍵指向一筆參考文獻條目，條目再指向一個真實的來源。Oleafly 讓這條鏈保持可見，這樣一次快速查詢就不會在日後變成一筆來路不明的參考文獻。

![Oleafly 的參考文獻面板。可在參照、引用與符號之間切換；用搜尋欄位篩選目前的檢視。](https://cdn.oleafly.com/images/screenshots/desktop/docs/references-panel-dark-window-v2.png#view=0,45,344,703)

## 寫作時引用

![「從專案引用」會開啟參考文獻選擇器。可依引用鍵、作者或標題搜尋；「尋找並新增引用」會開啟線上查詢。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-citation-picker-dark-window-v2.png#view=415,77,365,467)

在 LaTeX 或 Typst 工具列中，選擇 **從專案引用**（`@` 圖示）。依引用鍵、作者或標題搜尋目前的參考文獻，然後選擇一個條目。

你也可以從 ⌘K 或 Ctrl+K 指令面板執行 **新增引用**。Oleafly 會插入適用於目前專案的語法：

- 在 LaTeX 中為 `\cite{key}`；
- 在 Typst 中為 `@key`，若主文件沒有 `#bibliography(...)`，會在主文件結尾加上這一行；
- 在 Markdown 中為 `[@key]`，必要時會在 front matter 加上 `bibliography:` 這一行。

連接 Zotero 後，**新增引用** 會先列出來自你 Zotero 文獻庫的符合結果。

## 從你的 Zotero 文獻庫引用

[連接好 Zotero](/docs/integrations/research-sources/#zotero)後，輸入 `@` 加上作者姓名的一部分、標題中的一個字、年份或引用鍵。你的整個 Zotero 文獻庫會顯示在專案自己的參考文獻旁邊。選擇一篇論文，Oleafly 會依文件原本的引用方式插入引用。LaTeX 會使用文件最常用的命令，例如 `\citep` 或 `\parencite`，Typst 會得到 `@key`，Markdown 則得到 `[@key]`。在既有的 `\cite{...}` 內輸入 `@`，會為它再加上一個鍵。

只有那一筆條目會加到專案的 `.bib` 檔案結尾，檔案的其餘部分維持原樣。已經在 `.bib` 中的論文（依它的鍵或 DOI 判斷）絕不會重複加入。條目絕不會包含你電腦上 PDF 的路徑。如果專案還沒有參考文獻那一行，Oleafly 會加上：LaTeX 用 `\bibliography` 或 `\addbibresource`，Typst 用 `#bibliography`，Markdown 則在 front matter 中加入 `bibliography:`。若有多個 `.bib` 檔案，Oleafly 會詢問一次哪個檔案要接收新的參考文獻，並記住你的答案。

第一次在以 `thebibliography` 環境手動列出參考文獻的 LaTeX 論文中從 Zotero 引用時，Oleafly 會提議把該清單移進 `.bib`。這樣一來，所有參考文獻就共用同一份編號清單。

### 讓 .bib 與 Zotero 保持同步

被引用的鍵若不在 `.bib` 中、卻存在於 Zotero，會提供 **從 Zotero 新增**。從 ⌘K 面板執行 **從 Zotero 新增缺少的引用**，可一次檢查所有被引用的鍵。它會加入 Zotero 有的條目、列出 Zotero 沒有的條目，並指出引用了你參考文獻中已有論文的鍵。

當論文在 Zotero 中有變更時，它的 `.bib` 條目會提供 **從 Zotero 更新**。面板中的 **從 Zotero 更新 .bib 條目** 會檢視每一筆有變更的條目。你手動編輯過的條目，只有在你確認後才會被取代。**同步 Zotero 文獻庫** 會重新讀取文獻庫。Oleafly 絕不會自行從 `.bib` 移除任何內容。

![貼上論文標題的一部分，並把它的 BibTeX 條目儲存到 refs.bib。](https://cdn.oleafly.com/images/gifs/desktop/add-citation.gif?v=2)

## 尋找並新增參考文獻

從選擇器中選擇 **尋找並新增引用**。可以從下列任一種開始：

- DOI，例如 `10.1145/3592979`；
- arXiv 編號，例如 `1706.03762`；
- ISBN-10 或 ISBN-13；
- PubMed 編號（PMID）；
- 包含上述任一識別碼的 URL；
- 論文標題。

DOI、arXiv、ISBN 與 PubMed 的查詢會使用它們的公開目錄。標題搜尋會回傳可能符合的結果，並附上作者、年份與發表場所，讓你自己選擇，而不是接受猜測。

檢視回傳的 BibTeX，然後選擇 **新增至 .bib 並引用**。Oleafly 會：

1. 為目前使用中的參考文獻加入不會衝突的鍵；
2. 當 DOI 已存在時，重複使用既有的條目；
3. 在目前游標處插入引用；
4. 立即重新整理檔案樹與參考文獻面板。

中繼資料可以編輯。請在記錄成為稿件的一部分之前先修正它。

當文件宣告了多個參考文獻時，對話框會顯示 **參考文獻** 選單。條目會加入你選擇的檔案，Oleafly 會記住該專案的選擇。

## Oleafly 如何選擇參考文獻

LaTeX 專案會依循實際生效的主文件中的宣告：

- `\addbibresource{references.bib}` 用於 `biblatex`；
- `\bibliography{references}` 用於 BibTeX 工作流程。

路徑的解析方式，與 TeX 工具鏈預期的副檔名和相對路徑行為相同。指向不存在檔案的宣告，會在該原始碼行回報，而不是悄悄寫到別處。

Typst 專案會依循 `#bibliography(...)` 呼叫，無論它指定的是一個檔案還是一份清單，也無論檔案是 BibTeX `.bib` 還是 Hayagriva `.yml` 與 `.yaml`。新的引用會加入文件宣告的檔案。如果該檔案是 Hayagriva，Oleafly 會先轉換 BibTeX 條目再寫入。當呼叫指定了多個檔案時，請在對話框的 **參考文獻** 選單中選擇目標。

Markdown 專案會依循 front matter 中的 `bibliography:` 欄位。

沒有宣告任何參考文獻時，Oleafly 會使用專案中的第一個 `.bib`。如果一個都沒有，它會建立 `references.bib`，並讓它出現在檔案樹與引用選擇器中。

專案有多個文獻庫時，加入記錄之前請先檢查所選的目標。

## 選擇 Typst 引用樣式

當 Typst 文件有 `#bibliography(...)` 呼叫時，參考文獻面板的 **引用** 檢視底部會顯示 **引用樣式** 選單。它會列出該專案 Typst 版本內建的樣式，以及專案中的所有 `.csl` 檔案。選擇樣式後，會把它寫進該呼叫的 `style:` 引數。沒有指定時，Typst 會使用 `ieee`。

在 LaTeX 中，請在原始碼裡設定樣式。`\bibliographystyle{` 會自動完成常見的 BibTeX 樣式；使用 `biblatex` 時，請用它的 `style=` 選項。

## 匯入整個參考文獻庫

在參考文獻面板中選擇 **匯入參考文獻庫**。你可以匯入檔案，或匯入你的 Zotero 文獻庫。

**從檔案**匯入時，選擇已匯出的文獻庫：

| 來源格式 | 檔案 |
| --- | --- |
| BibTeX | `.bib` |
| RIS | `.ris` |
| EndNote XML | `.xml` |
| Zotero RDF | `.rdf` |

**從 Zotero** 匯入時，先在 **設定 → 整合 → Zotero** 連接一次你的 zotero.org 帳號，然後在 Zotero 卡片上選擇 **匯入 Zotero 文獻庫**。Oleafly 最多匯入 5,000 個項目。[連接研究來源](/docs/integrations/research-sources/#zotero)會逐步說明設定方式。

Oleafly 會把記錄對應成 BibTeX，並略過 DOI 已存在於目標文獻庫，或已出現在同一批較前面位置的參考文獻。它會建立不會衝突的鍵，並一次寫入附加結果。訊息會說明加入了多少筆參考文獻、有多少筆原本就有。匯入文獻庫不會在游標處插入引用。

匯入後，在引用選擇器中搜尋新的條目，並對照原始目錄抽查幾筆。

## 整理參考文獻庫

參考文獻面板可以在變更檔案之前預覽整理結果。

1. 開啟專案，在參考文獻面板中選擇 **整理參考文獻庫**。
2. 專案有多個 `.bib` 檔案時，選擇其中一個。
3. 閱讀動作清單與前後差異。
4. 檢查每一項建議的鍵重新命名、移除的 DOI 重複項目與提醒。
5. 預覽符合你的意圖之後才套用。

清理工具會把鍵重新命名為一致的「作者-年份-標題」模式，並更新整個專案原始檔中的引用。只有在保留下來的條目保有被移除條目的每個欄位時，才會移除 DOI 重複項目。DOI 記錄衝突與標題相似的項目會標記出來供你檢視，而不會憑臆測合併。

註解與 BibTeX 字串定義都會保留。套用時會確認文獻庫仍與預覽相符，並在變更檔案之前寫入備份。較大的差異在預覽中只顯示前 500 行；套用變更時仍會使用完整的檔案。

:::caution[套用前先檢視]
兩個版次、翻譯本、預印本與期刊版本，或標題相似的論文，可能本來就是刻意分開的。手動合併任何內容之前，請先閱讀提醒並比對實際的來源。
:::

## 自動完成與瀏覽參考文獻

在 `\cite{}`、`\citep{}`、`\citet{}`、`\parencite{}` 與 `\textcite{}` 這類 LaTeX 引用命令中，自動完成會搜尋專案的每個 `.bib` 檔案。在 Typst 中，`@` 會從 `.bib` 與 Hayagriva 檔案中自動完成鍵。連接 Zotero 後，清單也會包含你的 Zotero 文獻庫。

當 `.bib` 檔案沒有開啟時被加入的條目（例如由助理或從 Zotero 加入），對它的引用會立即解析。你不必先在文件中輸入任何內容。

- F12 或按住修飾鍵點選，可從引用鍵跳到它的條目。
- ⇧F12 會列出某個來源的每一處使用。
- F2 會在原始檔與參考文獻檔案中重新命名某個鍵。
- 將滑鼠停在上面會顯示目標；未解析或有歧義的鍵會在編譯之前標記出來。

[程式碼智慧](/docs/code-intelligence/)說明完整的導覽模型。

## 引用 Oleafly

如果 Oleafly 協助完成了一篇論文，請從指令面板，或從參考文獻面板 **引用** 檢視的底部，執行 **在這篇論文中引用 Oleafly**。Oleafly 會把鍵為 `oleafly` 的條目加入文件所宣告的參考文獻，格式為 BibTeX；若是 Hayagriva 檔案，則為 Hayagriva。訊息會指出檔案與要使用的語法，例如 `\cite{oleafly}` 或 `@oleafly`，旁邊有 **復原**。如果條目已經存在，則會改為提醒你它的鍵。

沒有參考文獻檔案的專案不會有任何變更，並會以對話框顯示條目讓你複製。同一個條目永遠都可以在[設定 → 說明與關於](/docs/settings/help/#cite-oleafly-in-a-paper)找到。

## 參考文獻建置與 Biber

對於 `biblatex`，當編譯器沒有產生可用的 `.bbl` 時，Oleafly 會重新執行與之搭配的 Biber 步驟。Biber 的訊息（包括缺少 `.bib` 路徑）會出現在編譯記錄與編輯器診斷中。

當 Biber 本身失敗時，編譯記錄會說明原因。它會指出缺少的系統程式庫，並建議使用 `\usepackage[backend=bibtex]{biblatex}`，作為不用 Biber 也能建置的辦法。在 Fedora 上，Oleafly 的 `.rpm` 會建議安裝 Biber 需要的兩個程式庫。

如果參照仍然未定義：

1. 檢查參考文獻的宣告與路徑。
2. 開啟 **記錄檔**，找出第一則 Biber 或參考文獻訊息。
3. 確認該引用鍵恰好只出現一次。
4. 儲存 `.bib` 檔案後重新編譯。

針對特定引擎的復原方式，請參閱[編譯與記錄檔](/docs/compiling/)和 [LaTeX 引擎與套件](/docs/latex-engines/)。

## 獨立的參考文獻工具

你不必開啟專案也能準備參考文獻：

- [引用產生器](/docs/tools/citation-generator/)接受識別碼、標題、結構化欄位或 BibTeX。
- [參考文獻產生器](/docs/tools/bibliography-generator/)建立並驗證清單。
- [依格式產生引用](/docs/tools/citation-styles/)比較八種格式。
- 專用工具可處理 [DOI](/docs/tools/doi-to-bibtex/)、[ISBN](/docs/tools/isbn-to-bibtex/)、[PubMed 編號](/docs/tools/pubmed-to-bibtex/)、[arXiv](/docs/tools/arxiv-citation-generator/) 與[網址](/docs/tools/url-to-bibtex/)。

手動編輯與引用格式化都在本機進行。識別碼與標題查詢則需要連線。[離線模式](/docs/settings/general/#offline-mode)會封鎖這些查詢，而既有的參考文獻自動完成與導覽仍可繼續運作。

## 尋找佐證，再加以驗證

[尋找引用](/docs/tools/find-citations/)會搜尋學術索引，或掃描開啟中的草稿，找出可能需要佐證的段落。引用論文之前請先閱讀它，並讓每項主張都不超出方法與結果所能證實的範圍。
