[@layout]: ../docs.layout.md

# Short links

Short gives a page a stable URL that follows its owning Source. Use it for QR
codes, slides, and printed material whose destination may change later.

```sh
bun run pmx plugins add short
bun run pmx short set /guides/start.page start
bun run pmx serve
```

Opening `/start` redirects to `/guides/start.page`. Static publication generates public redirect pages with a fallback link.

---

## Author a short link

Store the definition on the destination Source:

```md
---
short: table/context-engineering
---
# Context engineering
```

This creates `/table/context-engineering`. Codes use lowercase letters and digits,
with single hyphens between words and slashes between segments. Omit the leading
slash. Codes must be unique and cannot collide with canonical pages or reserved
routes. Run `bun run pmx lint` to inspect conflicts.

The redirect resolves the owning Source's current canonical path. Moving the
Source preserves its short link. Each Source owns at most one definition.

---

## Redirect parameters

Use the object form to add or remove query parameters:

```yaml
short:
  code: workshop
  params:
    via: qr
    campaign: fall
    preview: null
```

Incoming query parameters are preserved. Plugin parameters override incoming
values, and Source parameters override Plugin values. Each override replaces all
incoming values for that key; `null` removes the key, while an empty string keeps
an empty value. Unrelated repeated parameters retain every value.

Configure shared parameters in the installed Plugin file:

```ts
import Short from "@pathmx/short"

export default Short({ params: { via: "qr" } })
```

---

## Manage ownership from the CLI

Commands inspect the complete local repository, including private Sources.
Use canonical Source IDs for destinations.

```sh
bun run pmx short list --format json
bun run pmx short inspect workshop
bun run pmx short set /guides/start.page workshop --param campaign=fall
bun run pmx short edit workshop --param campaign=winter --omit-param preview
bun run pmx short edit workshop --unset-param campaign
bun run pmx short retarget workshop /guides/next.page
bun run pmx short remove workshop --confirm workshop
```

`edit --unset-param` removes a Source override, restoring Plugin or incoming
values. `--omit-param` stores `null`, removing that parameter from the redirect.
Repeat parameter flags to edit different keys in one command.

`retarget` transfers the entire definition, including its parameters, to another
page. The destination must not already own a short definition. `set` requires
`--replace <current-code>` when replacing an existing code; `remove` requires
`--confirm <code>`. Both operations remove the old public URL, so use `retarget`
to preserve a printed link while changing its destination.

When a separate running server watches these files, the URL can be briefly
unavailable during a transfer. Existing redirects work normally between transfers;
retargeting does not yet guarantee uninterrupted availability across processes.

`list` and `inspect` include Core route diagnostics. Mutations validate the final
Source changes and reject stale storage before committing.

---

## Static publication

Public aliases export as HTML redirect pages. A small script preserves incoming
query parameters and applies the same overrides as the live server. Without
JavaScript, the ordinary fallback link includes configured parameters but cannot
incorporate the incoming query. Destinations respect the publication origin and
base path. Private aliases are omitted, and export records no visits.

---

## Access and activity

Short uses Core's destination admission. A short URL does not grant access to its
owning Source. Successful redirects return `307` with `Cache-Control: no-store`.

Short owns the server Event `short.visit`, emitted after an admitted GET redirect.
Its data contains `code`, the owning `source` ID, and the destination pathname.
Query parameters are not included. HEAD requests do not emit the Event.

Short works independently of [Analytics](../hosting/analytics.reference). When
Analytics is installed, the Event's tracking declaration makes this activity
available to Analytics under its configured collection policy.