# External Links

> Add external URLs to the header or the sidebar.

The `links` list attaches URLs to the header or the sidebar. Each entry renders as a plain link.

## Basic usage

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

## Fields

| Field      | Default        | Use                                                                                                                 |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `url`      | none, required | The link's URL, absolute or root-relative.                                                                          |
| `title`    | none, required | Visible label.                                                                                                      |
| `position` | `header`       | Where the link renders: `header` or `sidebar`.                                                                      |
| `prefix`   | none           | Show the link only on pages under this folder, such as `/api/`.                                                     |
| `icon`     | none           | A [built-in icon](/authoring/rich-elements/#icons) before the title, such as `github`; an unknown name is an error. |

Any other field is an error. A root-relative `url` gets the `base` prefix like every other URL in the build.

## Header links

By default, links render in `<htmlpress-links>` in the header, between the site title and the theme toggle. When they outgrow the header, search shrinks to its icon, then the last links fold into a **More** menu, an icon on a phone.

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

## Sidebar links

Set `position: sidebar` to render inside the left sidebar, at the end of `<htmlpress-nav>`, below the pages.

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

For a per-page "Edit on GitHub" link, use `edit` rather than a link: its URL is followed by each page's source path, and the link renders in `<htmlpress-edit>` beside the page.

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

## Scoping a link to a section

A `prefix` shows a link only on the pages whose URL starts with it, for a per-section shortcut such as "Report issue". Like a section's prefix, it starts and ends with `/`.

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

## See also

- [Article Sections](/customization/article-sections/): the folders a scoped link would target.
- [Site Metadata](/customization/site-metadata/): the brand title and logo that sit next to header links.