feat(cli,docs): links to our sites say where they came from (#7178)

README links to hyperframes.studio, hyperframes.heygen.com and heygen.com
carry utm_source=github&utm_medium=readme, the values the README's download
links already use. Three README links went through docs redirects that drop
the query string (/showcase, /guides/claude-design, /guides/open-design);
they now point at the pages themselves.

The docs navbar's Community and changelog links carry src=docs-navbar, and
the export page's reinstall link src=docs-export, beside the existing docs-*
tags.

Links the CLI prints to our sites (init's docs links, the Lambda docs, the
publish claim URL, the HeyGen API-key page) carry utm_source=cli. Discord
invites stay untagged.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Wang
2026-11-04 23:19:51 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 4d9a4e4e86
commit fa318d9727
10 changed files with 104 additions and 59 deletions
+50 -50
View File
@@ -17,12 +17,12 @@
<p align="center"><b>Write HTML. Render video. Built for agents.</b></p>
<p align="center">
<a href="https://hyperframes.studio/studio">Studio</a> |
<a href="https://hyperframes.heygen.com/quickstart">Quickstart</a> |
<a href="https://hyperframes.heygen.com/showcase">Showcase</a> |
<a href="https://hyperframes.studio/">Playground</a> |
<a href="https://hyperframes.heygen.com/catalog/blocks/data-chart">Catalog</a> |
<a href="https://hyperframes.heygen.com/introduction">Docs</a> |
<a href="https://hyperframes.studio/studio?utm_source=github&utm_medium=readme">Studio</a> |
<a href="https://hyperframes.heygen.com/quickstart?utm_source=github&utm_medium=readme">Quickstart</a> |
<a href="https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme">Showcase</a> |
<a href="https://hyperframes.studio/?utm_source=github&utm_medium=readme">Playground</a> |
<a href="https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme">Catalog</a> |
<a href="https://hyperframes.heygen.com/introduction?utm_source=github&utm_medium=readme">Docs</a> |
<a href="https://discord.gg/fzbdWyjphr">Discord</a>
</p>
@@ -124,7 +124,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and
| `/reverse-any-video` | Rebuilding any video file as an editable HyperFrames project (motion graphics, talking heads, live action, AI-generated footage), checked frame by frame against the original. HyperFrames Pro. |
| `/style-sampling` | Making a new episode on your topic in one of five proven styles: Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime. HyperFrames Pro. |
For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design).
For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design) and [Open Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design).
### Manually with the CLI
@@ -139,7 +139,7 @@ npx hyperframes render # render to MP4
## What You Can Build
Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/showcase) for finished videos you can watch, read, run, and remix.
Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme) for finished videos you can watch, read, run, and remix.
- Product launch videos and feature announcements
- PR walkthroughs with animated code diffs, narration, and captions
@@ -159,57 +159,57 @@ The output is a `DESIGN.md` superset your whole toolchain can read. Atoms stay s
<table>
<tr>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/biennale-yellow"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/biennale-yellow.png" alt="Biennale Yellow" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/biennale-yellow">Biennale Yellow</a></b>
<a href="https://hyperframes.studio/design/biennale-yellow?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/biennale-yellow.png" alt="Biennale Yellow" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/biennale-yellow?utm_source=github&utm_medium=readme">Biennale Yellow</a></b>
</td>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/blockframe"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/blockframe.png" alt="BlockFrame" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/blockframe">BlockFrame</a></b>
<a href="https://hyperframes.studio/design/blockframe?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/blockframe.png" alt="BlockFrame" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/blockframe?utm_source=github&utm_medium=readme">BlockFrame</a></b>
</td>
</tr>
<tr>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/blue-professional"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/blue-professional.png" alt="Blue Professional" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/blue-professional">Blue Professional</a></b>
<a href="https://hyperframes.studio/design/blue-professional?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/blue-professional.png" alt="Blue Professional" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/blue-professional?utm_source=github&utm_medium=readme">Blue Professional</a></b>
</td>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/bold-poster"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/bold-poster.png" alt="Bold Poster" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/bold-poster">Bold Poster</a></b>
<a href="https://hyperframes.studio/design/bold-poster?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/bold-poster.png" alt="Bold Poster" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/bold-poster?utm_source=github&utm_medium=readme">Bold Poster</a></b>
</td>
</tr>
<tr>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/broadside"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/broadside.png" alt="Broadside" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/broadside">Broadside</a></b>
<a href="https://hyperframes.studio/design/broadside?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/broadside.png" alt="Broadside" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/broadside?utm_source=github&utm_medium=readme">Broadside</a></b>
</td>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/capsule"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/capsule.png" alt="Capsule" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/capsule">Capsule</a></b>
<a href="https://hyperframes.studio/design/capsule?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/capsule.png" alt="Capsule" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/capsule?utm_source=github&utm_medium=readme">Capsule</a></b>
</td>
</tr>
<tr>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/cartesian"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/cartesian.png" alt="Cartesian" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/cartesian">Cartesian</a></b>
<a href="https://hyperframes.studio/design/cartesian?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/cartesian.png" alt="Cartesian" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/cartesian?utm_source=github&utm_medium=readme">Cartesian</a></b>
</td>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/cobalt-grid"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/cobalt-grid.png" alt="Cobalt Grid" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/cobalt-grid">Cobalt Grid</a></b>
<a href="https://hyperframes.studio/design/cobalt-grid?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/cobalt-grid.png" alt="Cobalt Grid" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/cobalt-grid?utm_source=github&utm_medium=readme">Cobalt Grid</a></b>
</td>
</tr>
<tr>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/coral"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/coral.png" alt="Coral" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/coral">Coral</a></b>
<a href="https://hyperframes.studio/design/coral?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/coral.png" alt="Coral" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/coral?utm_source=github&utm_medium=readme">Coral</a></b>
</td>
<td width="50%" align="center">
<a href="https://hyperframes.studio/design/creative-mode"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/creative-mode.png" alt="Creative Mode" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/creative-mode">Creative Mode</a></b>
<a href="https://hyperframes.studio/design/creative-mode?utm_source=github&utm_medium=readme"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/design-templates/creative-mode.png" alt="Creative Mode" width="100%"></a>
<br><b><a href="https://hyperframes.studio/design/creative-mode?utm_source=github&utm_medium=readme">Creative Mode</a></b>
</td>
</tr>
</table>
Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design).
Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design?utm_source=github&utm_medium=readme).
## How It Works
@@ -253,16 +253,16 @@ Preview instantly in the browser. Render locally or in Docker. The renderer seek
HyperFrames is the open-source rendering engine, plus a growing set of tools around HTML-native video creation.
| Piece | Status | What it does |
| ------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects |
| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio |
| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects |
| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss |
| Studio | Available, evolving | Browser surface for previewing and editing compositions |
| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI |
| [hyperframes.studio](https://hyperframes.studio/) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects |
| [frame.md](https://hyperframes.studio/design) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from |
| Piece | Status | What it does |
| ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects |
| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio |
| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects |
| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss |
| Studio | Available, evolving | Browser surface for previewing and editing compositions |
| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI |
| [hyperframes.studio](https://hyperframes.studio/?utm_source=github&utm_medium=readme) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects |
| [frame.md](https://hyperframes.studio/design?utm_source=github&utm_medium=readme) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from |
## Catalog
@@ -274,7 +274,7 @@ npx hyperframes add instagram-follow # social overlay
npx hyperframes add data-chart # animated chart
```
Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart).
Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme).
## Why HyperFrames?
@@ -298,19 +298,19 @@ HyperFrames is inspired by [Remotion](https://www.remotion.dev). Both tools rend
| Distributed rendering | Local and AWS Lambda render paths | Remotion Lambda, mature cloud renderer |
| License | Apache 2.0 | Source-available Remotion License |
Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion).
Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion?utm_source=github&utm_medium=readme).
## Documentation
Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction)
Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction?utm_source=github&utm_medium=readme)
- [Quickstart](https://hyperframes.heygen.com/quickstart)
- [Showcase](https://hyperframes.heygen.com/showcase)
- [Guides](https://hyperframes.heygen.com/guides/gsap-animation)
- [API Reference](https://hyperframes.heygen.com/packages/core)
- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart)
- [Examples](https://hyperframes.heygen.com/examples)
- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda)
- [Quickstart](https://hyperframes.heygen.com/quickstart?utm_source=github&utm_medium=readme)
- [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme)
- [Guides](https://hyperframes.heygen.com/guides/gsap-animation?utm_source=github&utm_medium=readme)
- [API Reference](https://hyperframes.heygen.com/packages/core?utm_source=github&utm_medium=readme)
- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme)
- [Examples](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme)
- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda?utm_source=github&utm_medium=readme)
## Packages
@@ -327,7 +327,7 @@ Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.he
## Community
HyperFrames is used in production at [HeyGen](https://www.heygen.com), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames.
HyperFrames is used in production at [HeyGen](https://www.heygen.com?utm_source=github&utm_medium=readme), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames.
- Questions and ideas: [Discord](https://discord.gg/fzbdWyjphr)
- Bugs and feature requests: [GitHub Issues](https://github.com/heygen-com/hyperframes/issues)
+2 -2
View File
@@ -326,13 +326,13 @@
"item": "Community",
"icon": "users",
"description": "Videos people made",
"href": "https://hyperframes.studio/?view=community"
"href": "https://hyperframes.studio/?view=community&src=docs-navbar"
},
{
"item": "App changelog",
"icon": "sparkles",
"description": "What's new in the app",
"href": "https://hyperframes.studio/changelog"
"href": "https://hyperframes.studio/changelog?src=docs-navbar"
}
]
},
+1 -1
View File
@@ -73,7 +73,7 @@ Watch the exported file once from start to end before you send it.
- **The video was made but could not be saved to your Downloads folder**: free up space or check that the Downloads
folder exists, then export again.
- **HyperFrames could not start its built-in FFmpeg**: the app may be damaged. Reinstall it from
[hyperframes.studio/studio](https://hyperframes.studio/studio).
[hyperframes.studio/studio](https://hyperframes.studio/studio?src=docs-export).
## Related topics
@@ -8,6 +8,7 @@
*/
import { c } from "../../ui/colors.js";
import { cliSourced } from "../../utils/sourceTag.js";
export interface UnconfiguredContext {
/** A human can act on guidance now — a TTY, or a coding agent driving the CLI. */
@@ -88,7 +89,7 @@ export function buildUnconfiguredLines(
"Sign in or sign up (browser OAuth, writes ~/.hyperframes — no per-repo .env):",
` ${c.accent("npx hyperframes auth login")} ${c.dim("# browser sign-in / sign-up")}`,
"",
"Or paste an existing HeyGen API key (get one at app.heygen.com/settings/api):",
`Or paste an existing HeyGen API key (get one at ${cliSourced("https://app.heygen.com/settings/api")}):`,
` ${c.accent("npx hyperframes auth login --api-key")} ${c.dim("# paste at the prompt")}`,
"",
...offlineEngineLines(engines),
+5 -2
View File
@@ -60,6 +60,7 @@ import {
VIEWPORT_META_SIZE_RE,
} from "@hyperframes/parsers";
import { decodableAudioStream } from "@hyperframes/parsers/media-streams";
import { cliSourced } from "../utils/sourceTag.js";
function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string {
const example = exampleFlag === "agent" ? "blank" : exampleFlag;
@@ -997,7 +998,9 @@ export default defineCommand({
console.log(
` ${c.dim('"Using /hyperframes, create a 15-second intro about [your topic]"')}`,
);
console.log(` ${c.dim("More patterns: hyperframes.heygen.com/prompting/overview")}`);
console.log(
` ${c.dim(`More patterns: ${cliSourced("https://hyperframes.heygen.com/prompting/overview")}`)}`,
);
console.log();
console.log(` ${c.accent("4.")} Preview in the browser:`);
console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run dev")}`);
@@ -1008,7 +1011,7 @@ export default defineCommand({
console.log(` ${c.accent("6.")} Render to MP4 when ready:`);
console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run render")}`);
console.log();
console.log(` ${c.dim("Full docs: hyperframes.heygen.com")}`);
console.log(` ${c.dim(`Full docs: ${cliSourced("https://hyperframes.heygen.com")}`)}`);
return;
}
@@ -109,7 +109,9 @@ describe("stagePrebuiltHandler with nothing to deploy", () => {
const message = noHandlerMessage(false);
expect(message).toMatch(/npm install -g @hyperframes\/aws-lambda@/);
expect(message).toMatch(/HYPERFRAMES_REPO_ROOT/);
expect(message).toMatch(/^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda$/m);
expect(message).toMatch(
/^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda\?utm_source=cli$/m,
);
expect(downloads).toEqual([]);
});
@@ -16,8 +16,9 @@ import { downloadFile } from "../../utils/download.js";
import { isMissingPackageError } from "../../utils/missingPackage.js";
import { VERSION } from "../../version.js";
import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";
import { cliSourced } from "../../utils/sourceTag.js";
const DOCS_URL = "https://hyperframes.heygen.com/deploy/aws-lambda";
const DOCS_URL = cliSourced("https://hyperframes.heygen.com/deploy/aws-lambda");
const HANDLER_CACHE_DIR = hyperframesCacheDir("lambda-handler");
type AdapterSdk = typeof import("@hyperframes/aws-lambda/sdk");
+2 -1
View File
@@ -29,6 +29,7 @@ import {
readTeamProject,
writeTeamProject,
} from "../utils/projectLink.js";
import { cliSourced } from "../utils/sourceTag.js";
export const examples: Example[] = [
["Publish the current project privately to a stable URL", "hyperframes publish"],
@@ -313,7 +314,7 @@ export default defineCommand({
} else {
const claimUrl = new URL(published.url);
claimUrl.searchParams.set("claim_token", published.claimToken);
console.log(` ${c.dim("Claim URL")} ${c.accent(claimUrl.toString())}`);
console.log(` ${c.dim("Claim URL")} ${c.accent(cliSourced(claimUrl.toString()))}`);
console.log(` ${c.dim("Access")} ${c.accent("Sign in required to claim")}`);
console.log();
console.log(
+27
View File
@@ -0,0 +1,27 @@
import { describe, expect, it } from "vitest";
import { cliSourced } from "./sourceTag.js";
describe("cliSourced", () => {
it("tags our sites with utm_source=cli, keeping the query and fragment", () => {
expect(cliSourced("https://hyperframes.heygen.com/prompting/overview")).toBe(
"https://hyperframes.heygen.com/prompting/overview?utm_source=cli",
);
expect(cliSourced("https://hyperframes.studio/p/abc?claim_token=t#top")).toBe(
"https://hyperframes.studio/p/abc?claim_token=t&utm_source=cli#top",
);
expect(cliSourced("https://app.heygen.com/settings/api")).toBe(
"https://app.heygen.com/settings/api?utm_source=cli",
);
});
it("leaves other hosts, look-alikes, an existing source and non-URLs alone", () => {
for (const url of [
"https://github.com/heygen-com/hyperframes",
"https://hyperframes.app/",
"https://notheygen.com/",
"https://hyperframes.studio/?utm_source=github",
"not a url",
])
expect(cliSourced(url)).toBe(url);
});
});
+10
View File
@@ -0,0 +1,10 @@
// A link the CLI prints to one of our sites says it came from the CLI; a link that already names a source keeps it.
const OUR_HOST = /(^|\.)(hyperframes\.studio|hyperframes\.heygen\.com|heygen\.com)$/;
export function cliSourced(url: string): string {
if (!URL.canParse(url)) return url;
const parsed = new URL(url);
if (!OUR_HOST.test(parsed.hostname) || parsed.searchParams.has("utm_source")) return url;
parsed.searchParams.set("utm_source", "cli");
return parsed.toString();
}