# 外部链接

> 在页眉或侧边栏中添加外部 URL。

`links` 列表把 URL 添加到页眉或侧边栏中。每个条目都渲染为一个普通链接。

## 基本用法

```yaml
include: docs/**/*.html
links:
  - title: GitHub
    url: https://github.com/acme/docs
```

## 字段

| 字段         | 默认值      | 用途                                                                |
| ---------- | -------- | ----------------------------------------------------------------- |
| `url`      | 无，必填     | 链接的 URL，可以是绝对 URL 或根相对 URL。                                       |
| `title`    | 无，必填     | 显示的文字。                                                            |
| `position` | `header` | 链接渲染的位置：`header` 或 `sidebar`。                                     |
| `prefix`   | 无        | 仅在该文件夹下的页面中显示此链接，例如 `/api/`。                                      |
| `icon`     | 无        | 标题前的[内置图标](/zh/authoring/rich-elements/#图标)，例如 `github`；未知的名称会报错。 |

其他任何字段都会报错。根相对的 `url` 会像构建中的其他 URL 一样加上 `base` 前缀。

## 页眉链接

默认情况下，链接渲染在页眉的 `<htmlpress-links>` 中，位于站点标题和主题切换按钮之间。当页眉放不下时，搜索会先缩小为图标，然后最后的几个链接会折叠进**更多**菜单（在手机上显示为图标）。

```yaml
links:
  - title: GitHub
    url: https://github.com/acme/docs
  - title: Docs
    url: /introduction.html
```

## 侧边栏链接

设置 `position: sidebar` 可将链接渲染在左侧边栏中，位于 `<htmlpress-nav>` 末尾、页面列表下方。

```yaml
links:
  - title: Chat
    url: https://discord.gg/example
    position: sidebar
```

对于每个页面的"编辑此页"链接，请使用 `edit` 而不是普通链接：它的 URL 后面会接上每个页面的源文件路径，链接渲染在页面旁的 `<htmlpress-edit>` 中。

```yaml
edit: https://github.com/acme/docs/edit/main/
```

## 将链接限定在某个分区

`prefix` 让链接只显示在 URL 以其开头的页面上，可用于诸如"报告问题"这类分区专属的快捷链接。与分区的前缀一样，它以 `/` 开头和结尾。

```yaml
links:
  - title: Report an API issue
    url: https://github.com/acme/api/issues
    prefix: /api/
```

## 另请参阅

- [文章分区](/zh/customization/article-sections/)：限定范围的链接所针对的文件夹。
- [站点元数据](/zh/customization/site-metadata/)：位于页眉链接旁边的品牌标题和 logo。