> ## 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-CN/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-CN/on-premises/configuration/overleaf-toolkit/authentication/public-access.md#page-access)。

关于管理员可以设置的其他内容，请参阅 [Overleaf Import API](https://ayakaleaf-pro.mintlify.site/zh-CN/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.