> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Open in Overleaf

> 在你的網站上加入一個連結，在你的執行個體中開啟一個 LaTeX 檔案或整個專案。

在你的網站、部落格或課程頁面上放置一個連結。任何按下它的人都會得到一個包含你的檔案、屬於自己的新專案。無需任何設定。

訪客需要在你的執行個體上擁有帳號。未登入的訪客會先進入登入頁面，登入後專案才會開啟。

此功能的頁面使用 Overleaf 這個名稱。你自己的連結或按鈕可以使用任何文字，例如 **Open in Ayakaleaf**。

## 查看範例

在你的網站上開啟 `/devs`，例如 `https://ayakaleaf.example.com/devs`。沒有任何選單連結到此頁面，因此請自行輸入網址。預設情況下，你必須登入才能查看。

![帶有 A LaTeX code snippet 和 A zipped project 按鈕的 Overleaf API 頁面](https://mintcdn.com/ayakaleaf-pro/PeD9iteXIf8j4GXw/images/on-premises/open-in-overleaf-devs.png?fit=max\&auto=format\&n=PeD9iteXIf8j4GXw\&q=85\&s=e0769b26bc5206799501cf44c0cf2c46)

Overleaf API 頁面

按一下 **A LaTeX code snippet** 或 **A zipped project**。一個包含該範例的新專案會開啟。

![專案 I am a Zip file，包含 main.tex、main2.tex 和 sample.bib 及其 PDF](https://mintcdn.com/ayakaleaf-pro/PeD9iteXIf8j4GXw/images/on-premises/open-in-overleaf-zip-project.png?fit=max\&auto=format\&n=PeD9iteXIf8j4GXw\&q=85\&s=0070a05e99c93a4e1ff11962d36a8d83)

來自壓縮檔範例的專案

## 連結到你網站上的檔案

**1. 建立連結**

將檔案網址經過 URL 編碼後放在 `/docs?snip_uri=` 之後：

```text theme={null}
https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fmain.tex
```

若是壓縮的專案，請使用 `zip_uri`：

```text theme={null}
https://ayakaleaf.example.com/docs?zip_uri=https%3A%2F%2Fexample.com%2Fproject.zip
```

你的執行個體會下載該檔案，因此它必須可以透過 HTTP 或 HTTPS 存取。私人網路上的網址會被拒絕，請參閱 [External URL](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/external-url.md)。

**2. 將它加入你的頁面**

```html theme={null}
<a href="https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fmain.tex">Open in Ayakaleaf</a>
```

**3. 按下連結**

新專案會在編輯器中開啟，其中只有一個儲存為 `main.tex` 的檔案。

![編輯器中的專案 Hello from a link，包含 main.tex 及其 PDF](https://mintcdn.com/ayakaleaf-pro/PeD9iteXIf8j4GXw/images/on-premises/open-in-overleaf-project.png?fit=max\&auto=format\&n=PeD9iteXIf8j4GXw\&q=85\&s=870760e85a1053dc1730663a74c48744)

從連結開啟的專案

每按一次都會建立另一個專案。該專案是一份副本，因此之後對你的檔案所做的變更不會同步到它。

## 將檔案放入連結

對於小型檔案，你無需託管任何內容：將其內容以 Base64 data URL 放入連結中。在 JavaScript 中：

```javascript theme={null}
const tex = '\\documentclass{article}\n\\begin{document}\nHello from a link.\n\\end{document}\n'
const link = 'https://ayakaleaf.example.com/docs?' + new URLSearchParams({
  snip_uri: 'data:application/x-tex;base64,' + btoa(tex),
  name: 'Hello from a link',
})
```

`btoa` 只接受 Latin-1 字元，因此請先將其他文字編碼為 UTF-8。若是壓縮的專案，請使用 `zip_uri` 和 `data:application/zip;base64,`。

長度超過約 8 KB 的連結會被拒絕，並出現錯誤 **414 Request-URI Too Large**。若內容更大，請託管檔案或使用[表單](#use-a-button-instead-of-a-link)。

## 選擇選項

將下列參數加入連結，或以隱藏欄位加入表單：

| 參數 | 作用 | 範例 |
| - | - | - |
| `name` | 為專案命名。若未提供，壓縮的專案會使用其 `\title` 中的名稱，其他情況則為 `Open in Overleaf project`。 | `name=My%20notes` |
| `engine` | 設定編譯器：`latex_dvipdf`、`pdflatex`、`xelatex` 或 `lualatex`。 | `engine=xelatex` |
| `main_document` | 設定主要 `.tex` 檔案，它會最先開啟。 | `main_document=thesis.tex` |
| `snip_uri[]`, `snip_name[]` | 匯入多個檔案，每個檔案依相同順序擁有自己的名稱。 | `snip_uri[]=.../a.tex&snip_name[]=a.tex` |

沒有 `\documentclass` 的 `.tex` 檔案會被包裝在標準文件中，因此可以立即編譯：

```latex theme={null}
\documentclass[12pt]{article}
\usepackage[english]{babel}
\usepackage{amsmath}
\usepackage{tikz}
\begin{document}
Your file
\end{document}
```

## 使用按鈕取代連結

表單傳送的參數與連結相同：

```html theme={null}
<form action="https://ayakaleaf.example.com/docs" method="post" target="_blank">
  <input type="hidden" name="snip_uri" value="https://example.com/main.tex">
  <input type="hidden" name="engine" value="xelatex">
  <button type="submit">Open in Ayakaleaf</button>
</form>
```

若要直接傳送 LaTeX 內容，純文字請使用 `snip`，經過 `encodeURIComponent` 處理的文字請使用 `encoded_snip`。

表單並非總是有效，因此除非你的檔案太長而無法放入連結，否則連結是較好的選擇：

| 表單所在位置 | 訪客已登入 | 訪客未登入 |
| - | - | - |
| 與你的執行個體位於相同網域或其子網域 | 專案開啟 | 登入頁面，不建立專案 |
| 位於其他網域 | 登入頁面，不建立專案 | 登入頁面，不建立專案 |

如果管理員設定了 `OVERLEAF_ALLOW_PUBLIC_ACCESS=true`，在上述所有情況下專案都會開啟，必要時會先登入。該設定也會向未登入的訪客開放其他頁面，請參閱 [Page Access](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/authentication/public-access.md#page-access)。

關於管理員可以設定的其他項目，請參閱 [Overleaf Import API](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/overleaf-import-api.md)。`/devs` 頁面上有更多範例。

## 如果專案沒有開啟

頁面會說明發生了什麼問題。**View the Overleaf API docs** 會帶你前往 `/devs`。

![帶有訊息 invalid url 和 View the Overleaf API docs 按鈕的 Open in Overleaf 頁面](https://mintcdn.com/ayakaleaf-pro/PeD9iteXIf8j4GXw/images/on-premises/open-in-overleaf-error.png?fit=max\&auto=format\&n=PeD9iteXIf8j4GXw\&q=85\&s=0fdd1309fab22f5aa1c80925377627c7)

執行個體無法使用的連結

| 訊息 | 原因 | 處理方式 |
| - | - | - |
| `no snippet, snip_uri or zip_uri provided` | 連結中沒有任何這些參數 | 檢查參數名稱 |
| `invalid url: ...` | 網址不是以 HTTP 或 HTTPS 開頭 | 使用 HTTP 或 HTTPS 網址，或 data URL |
| `could not download ... (HTTP 404)` | 該網址上沒有此檔案 | 檢查網址 |
| `could not download ... (HTTP 403)` | 該網址位於私人網路上 | 將檔案託管在你的執行個體可以存取的位置 |
| `zip_uri did not resolve to a zip archive` | `zip_uri` 指向的檔案不是 zip 檔案 | 檢查檔案 |
| `invalid base64 data url` | data URL 已損毀 | 重新編碼檔案，並對連結進行 URL 編碼 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.