Repository Embed

<div align="center">
<h1>
  Repository Embed
</h1>
A web component for embedding code repositories on the web.
</div>
<br/>

Zero-dependency, configurable `<repo-card>` web component for displaying (mainly Git) repository details with links to the forge. It supports GitHub, GitLab, Gitea, Forgejo, Codeberg, Bitbucket, Tangled, SourceHut, Azure DevOps, and self-hosted instances.

_This package is not affiliated with any of the supported forges._

- [Available on NPM](https://npmx.dev/package/repository-embed)

## Usage

Install the web component by whatever means you prefer, then import it:

```html
<script src="repository-embed.js"></script>
```

Use the web component:

```html
<repo-card repo="github:sindresorhus/got"></repo-card>
<repo-card repo="https://gitlab.com/gitlab-org/gitlab-runner"></repo-card>
<repo-card repo="codeberg:forgejo/forgejo" details="all"></repo-card>
<repo-card repo="github:sindresorhus/got" branch="electron-store-test"></repo-card>
```

## Attributes

| Attribute | Required | Description                                    | Values                                                                                             |
| --------- | -------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `repo`    | Yes      | The repository to display.                     | `owner/repo`, a forge-prefixed shorthand, a repository URL, or a clone URL                         |
| `host`    | No       | The forge host for shorthand references.       | A hostname such as `git.example.com`                                                               |
| `forge`   | No       | Force a specific forge implementation.         | `github`, `gitlab`, `gitea`, `forgejo`, `bitbucket`, `tangled`, `sourcehut`, `azure`, or `generic` |
| `api`     | No       | Override the forge API base URL.               | For example `https://git.example.com/api/v1`                                                       |
| `branch`  | No       | The branch to display and use for branch data. | Any branch name; defaults to the repository's default branch                                       |
| `details` | No       | The metadata fields to display.                | `stars,forks,language` (default), `all`, `""`, or a comma-separated list                           |

`repo` accepts an `owner/repo` shorthand, a forge prefix (`github:`, `gitlab:`, `bitbucket:`, `tangled:`, `codeberg:`, `gitea:`, `forgejo:`, `sourcehut:`, or `azure:`), a repository URL, or a clone URL. A plain `owner/repo` reference requires `host` unless `forge` or `api` supplies a default. For self-hosted instances, set `host` and `forge`, plus `api` when the API is on a subpath:

```html
<repo-card repo="owner/repo" host="git.example.com" forge="gitea"></repo-card>
<repo-card repo="owner/repo" host="example.com" forge="forgejo" api="https://example.com/gitea/api/v1"></repo-card>
```

Unknown hosts are probed for a supported API and fall back to a link-only card. SourceHut and Azure DevOps are rendered as link-only cards. Use `forge="generic"` to request this behaviour explicitly.

Setting `branch` validates the branch and uses its latest commit for `updated` and `pushed` where supported. Invalid branches show an error while link-only cards display the name without validation.

Available `details` fields: `stars`, `forks`, `watchers`, `issues`, `pulls`, `language`, `licence`/`license`, `release`, `branch`, `updated`, `created`, `pushed`, `size`, `topics`, `homepage`, `clone`, `owner`, `forge`, `archived`, `mirror`, `visibility`, `image`. Fields that a forge does not expose are omitted.

## Supported forges

| Forge                    | Hosts                                    | Notes                                                              |
| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
| GitHub                   | `github.com`, GitHub Enterprise          | REST API. Unauthenticated requests are rate limited.               |
| GitLab                   | `gitlab.com`, self-hosted                | API v4. Nested groups supported.                                   |
| Gitea / Forgejo          | `gitea.com`, `codeberg.org`, self-hosted | API v1. Including Gogs.                                            |
| Bitbucket Cloud          | `bitbucket.org`                          | API 2.0. Watchers are shown as stars.                              |
| Tangled                  | `tangled.org`, `tangled.sh`              | Uses the appview and repository knot; some fields are unavailable. |
| SourceHut / Azure DevOps | `git.sr.ht`, `dev.azure.com`             | Link-only.                                                         |
| Other hosts              | Any                                      | Auto-detected, with a link-only fallback.                          |

## Theming

By default, each supported host supplies its own light/dark palette. Unknown hosts use the generic palette below. Override any property to customise the card:

```css
repo-card {
	--repo-bg: light-dark(oklch(100% 0 0), oklch(17.1% 0 0));
	--repo-border: light-dark(oklch(85.14% 0 0), oklch(26.9% 0 0));
	--repo-border-width: 1px;
	--repo-border-hover: light-dark(oklch(71.5% 0 0), oklch(37.1% 0 0));
	--repo-border-strong: light-dark(oklch(71.5% 0 0), oklch(37.1% 0 0));
	--repo-bg-muted: light-dark(oklch(95.5% 0.001 286.76), oklch(23.6% 0 0));
	--repo-text: light-dark(oklch(4.6% 0 0), oklch(98.2% 0 0));
	--repo-muted: light-dark(oklch(19.8% 0 0), oklch(84.9% 0 0));
	--repo-subtle: light-dark(oklch(28% 0 0), oklch(77.3% 0 0));
	--repo-accent: light-dark(oklch(52% 0.14 48), oklch(79% 0.12 58));
	--repo-danger: light-dark(oklch(50.5% 0.213 27.518), oklch(70.4% 0.191 22.216));
	--repo-radius: 0.5rem;
	--repo-radius-sm: 0.375rem;
	--repo-radius-xs: 0.25rem;
	--repo-font: "Comic Sans";
	--repo-font-mono: "Comic Mono";
}
```

`--repo-border-width` controls the thickness of the card border. `--repo-radius` controls the card radius. `--repo-radius-sm` and `--repo-radius-xs` control tags, small details, and the preview image radius. The Geist and Geist Mono fonts are used when available, with system fallbacks otherwise.