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.

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.

Store the definition on the destination Source:

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

Use the object form to add or remove query parameters:

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:

import Short from "@pathmx/short"

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

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

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.

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.

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. When Analytics is installed, the Event's tracking declaration makes this activity available to Analytics under its configured collection policy.