External Links

Updated Nov 1, 2026

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

Basic usage

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 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.

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

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

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.

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 /.

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