Skip to content

Open source CapCut alternative.

TypeScript

feat(site): the blog at /blog with a link in the footer

David Lea11f7eb32448
diff --git a/site/src/app/_components/landing/Footer.tsx b/site/src/app/_components/landing/Footer.tsx
index c6705ecd..ce26c826 100644
--- a/site/src/app/_components/landing/Footer.tsx
+++ b/site/src/app/_components/landing/Footer.tsx
@@ -25,7 +25,10 @@ export function Footer() {
const linkGroups: FooterColumn[] = [
{
title: "Product",
- links: [{ href: GITHUB_REPO_URL, label: "GitHub" }],
+ links: [
+ { href: GITHUB_REPO_URL, label: "GitHub" },
+ { href: "/blog", label: "Blog" },
+ ],
},
{
title: "Legal",
diff --git a/site/src/app/cut/_components/landing/CutFooter.tsx b/site/src/app/cut/_components/landing/CutFooter.tsx
index 3ba978d5..8a5a5a32 100644
--- a/site/src/app/cut/_components/landing/CutFooter.tsx
+++ b/site/src/app/cut/_components/landing/CutFooter.tsx
@@ -19,6 +19,7 @@ export function CutFooter() {
links: [
{ href: GITHUB_REPO_URL, label: "GitHub" },
{ href: DISCORD_URL, label: "Discord" },
+ { href: "/blog", label: "Blog" },
],
},
{
diff --git a/site/src/app/cut/blog/[slug]/page.tsx b/site/src/app/cut/blog/[slug]/page.tsx
new file mode 100644
index 00000000..f7afcb63
--- /dev/null
+++ b/site/src/app/cut/blog/[slug]/page.tsx
@@ -0,0 +1,202 @@
+import { ArrowLeft } from "lucide-react";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+
+import { BlogHeaderImage } from "@/app/cut/blog/_components/BlogHeaderImage";
+import { BlogShell } from "@/app/cut/blog/_components/BlogShell";
+import { formatBlogDate, titleCaseTag } from "@/app/cut/blog/_components/blogDate";
+import { ScrollToHash, TableOfContents } from "@/app/cut/blog/_components/TableOfContents";
+import { DONKEYCUT_CANONICAL } from "@/cut/lib/hosts";
+import { blogPath } from "@/lib/blog/keys";
+import { getPost, listPublishedSlugs, type BlogPostPage } from "@/lib/blog/read";
+import { PostArticle } from "@/lib/blog/render";
+
+type Params = { params: Promise<{ slug: string }> };
+
+// Cache Components needs at least one param; a blog with no published post
+// gets a placeholder the page answers with 404.
+export async function generateStaticParams() {
+ const slugs = await listPublishedSlugs();
+ return slugs.length > 0 ? slugs.map((slug) => ({ slug })) : [{ slug: "__placeholder__" }];
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+ const { slug } = await params;
+ const post = await getPost(slug);
+ if (!post) return {};
+ const title = `${post.seoTitle || post.title} | Donkey Cut`;
+ const description = post.summary || post.excerpt;
+ const canonical = post.canonicalUrl || `${DONKEYCUT_CANONICAL}${blogPath(slug)}`;
+ const image = post.headerUrl ?? post.thumbnailUrl;
+ return {
+ title,
+ description,
+ keywords: Array.from(new Set([...post.keywords, ...post.tags])),
+ alternates: { canonical },
+ robots: post.noIndex || post.status !== "PUBLISHED" ? { index: false, follow: false } : undefined,
+ openGraph: {
+ title,
+ description,
+ url: `${DONKEYCUT_CANONICAL}${blogPath(slug)}`,
+ siteName: "Donkey Cut",
+ type: "article",
+ publishedTime: post.publishedAt ?? undefined,
+ modifiedTime: post.revisedAt ?? post.publishedAt ?? undefined,
+ tags: post.tags,
+ images: image ? [{ url: image, alt: post.headerAlt ?? post.title }] : undefined,
+ },
+ twitter: {
+ card: image ? "summary_large_image" : "summary",
+ title,
+ description,
+ images: image ? [image] : undefined,
+ },
+ };
+}
+
+export const instant = true;
+
+function jsonLd(post: BlogPostPage, url: string) {
+ const article = {
+ "@context": "https://schema.org",
+ "@type": "BlogPosting",
+ headline: post.title,
+ description: post.summary || post.excerpt,
+ url,
+ mainEntityOfPage: { "@type": "WebPage", "@id": url },
+ inLanguage: "en",
+ datePublished: post.publishedAt ?? undefined,
+ dateModified: post.revisedAt ?? post.publishedAt ?? undefined,
+ publisher: {
+ "@type": "Organization",
+ name: "Donkey",
+ url: DONKEYCUT_CANONICAL,
+ logo: { "@type": "ImageObject", url: `${DONKEYCUT_CANONICAL}/donkey-logo.svg` },
+ },
+ ...(post.headerUrl ? { image: [post.headerUrl] } : {}),
+ ...(post.keywords.length > 0 ? { keywords: post.keywords } : {}),
+ ...(post.tags.length > 0 ? { articleSection: post.tags } : {}),
+ };
+ const faq =
+ post.faq.length > 0
+ ? {
+ "@context": "https://schema.org",
+ "@type": "FAQPage",
+ mainEntity: post.faq.map((item) => ({
+ "@type": "Question",
+ name: item.question,
+ acceptedAnswer: { "@type": "Answer", text: item.answer },
+ })),
+ }
+ : null;
+ return { article, faq };
+}
+
+function BackLink({ large }: { large?: boolean }) {
+ return (
+ <Link
+ href="/blog"
+ className={
+ large
+ ? "inline-flex items-center gap-2 text-base font-semibold text-ink no-underline transition-colors hover:text-coral"
+ : "mb-6 inline-flex items-center gap-2 text-sm text-[#666] no-underline transition-colors hover:text-ink md:mb-8"
+ }
+ >
+ <ArrowLeft className="size-4" />
+ {large ? "Back to all posts" : "Back to blog"}
+ </Link>
+ );
+}
+
+// Everything under the params read. The post itself is a cached read, so this
+// resolves from the cache for a published slug; Draft Mode re-runs it.
+async function Post({ params }: Params) {
+ const { slug } = await params;
+ const post = await getPost(slug);
+ if (!post) notFound();
+ const url = `${DONKEYCUT_CANONICAL}${blogPath(slug)}`;
+ const { article, faq } = jsonLd(post, url);
+ const revised =
+ post.revisedAt && post.publishedAt && new Date(post.revisedAt) > new Date(post.publishedAt)
+ ? formatBlogDate(post.revisedAt)
+ : null;
+ return (
+ <>
+ <ScrollToHash />
+ <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(article) }} />
+ {faq ? <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(faq) }} /> : null}
+ {post.status !== "PUBLISHED" ? (
+ <div className="mb-6 flex flex-wrap items-center justify-between gap-3 rounded-2xl border-2 border-ink bg-coral px-4 py-3 text-sm font-semibold text-ink">
+ <span>Draft preview. Only you can see this page.</span>
+ <a href="/api/blog/preview/exit" className="underline underline-offset-2">
+ Exit preview
+ </a>
+ </div>
+ ) : null}
+ <BackLink />
+ {post.headerUrl ? <BlogHeaderImage src={post.headerUrl} alt={post.headerAlt ?? post.title} focus={post.headerFocus} /> : null}
+ <div className="flex flex-col gap-12 lg:grid lg:grid-cols-[minmax(0,1fr)_16rem] lg:items-start">
+ <div className="w-full max-w-[72ch]">
+ <header className="mb-8 md:mb-12">
+ {post.tags.length > 0 ? (
+ <div className="mb-4 flex flex-wrap items-center gap-2">
+ {post.tags.map((tag) => (
+ <span
+ key={tag}
+ className="inline-block rounded-md bg-ink px-2.5 py-1 text-[11px] font-semibold tracking-[0.08em] text-white uppercase"
+ >
+ {titleCaseTag(tag)}
+ </span>
+ ))}
+ </div>
+ ) : null}
+ <h1 className="mb-4 text-3xl font-semibold leading-tight text-balance text-ink md:text-5xl">{post.title}</h1>
+ <div className="flex flex-wrap items-center gap-2 text-sm text-[#666]">
+ {post.publishedAt ? <time dateTime={post.publishedAt}>{formatBlogDate(post.publishedAt)}</time> : null}
+ {revised ? (
+ <>
+ <span>&bull;</span>
+ <span>Updated {revised}</span>
+ </>
+ ) : null}
+ </div>
+ {post.summary ? <p className="mt-5 max-w-[60ch] text-lg leading-8 text-[#454545]">{post.summary}</p> : null}
+ </header>
+ <PostArticle slug={slug} />
+ </div>
+ <aside className="sticky top-24 hidden w-64 justify-self-end lg:block">
+ <TableOfContents headings={post.headings} />
+ </aside>
+ </div>
+ <div className="mt-12 pt-6 md:mt-16 md:pt-8">
+ <BackLink large />
+ </div>
+ </>
+ );
+}
+
+function PostSkeleton() {
+ return (
+ <div aria-hidden className="animate-pulse">
+ <div className="mb-8 h-60 rounded-2xl border-2 border-ink/10 bg-cream" />
+ <div className="max-w-[72ch] space-y-4">
+ <div className="h-10 w-3/4 rounded-lg bg-ink/10" />
+ <div className="h-4 w-1/3 rounded bg-ink/10" />
+ <div className="h-4 w-full rounded bg-ink/10" />
+ <div className="h-4 w-5/6 rounded bg-ink/10" />
+ </div>
+ </div>
+ );
+}
+
+export default function BlogPostPage({ params }: Params) {
+ return (
+ <BlogShell>
+ <Suspense fallback={<PostSkeleton />}>
+ <Post params={params} />
+ </Suspense>
+ </BlogShell>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogCta.tsx b/site/src/app/cut/blog/_components/BlogCta.tsx
new file mode 100644
index 00000000..747020dc
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogCta.tsx
@@ -0,0 +1,50 @@
+import { PillButton } from "@/app/_components/landing/LandingPrimitives";
+
+// The call to action an article can drop in with <BlogCTA /> or <InlineCTA />.
+// Copy and target default to the product; a post can override any of them.
+export type BlogCtaProps = {
+ variant?: "inline" | "banner";
+ title?: string;
+ description?: string;
+ buttonText?: string;
+ buttonHref?: string;
+};
+
+export const CTA_DEFAULTS = {
+ title: "Edit your next video with Donkey Cut",
+ description:
+ "A free, open source video editor. Edit with chat, generate video, images, voiceovers and music, and keep your projects on your own machine.",
+ buttonText: "Open Donkey Cut",
+ buttonHref: "/app",
+};
+
+export function BlogCTA({
+ variant = "inline",
+ title = CTA_DEFAULTS.title,
+ description = CTA_DEFAULTS.description,
+ buttonText = CTA_DEFAULTS.buttonText,
+ buttonHref = CTA_DEFAULTS.buttonHref,
+}: BlogCtaProps) {
+ if (variant === "banner") {
+ return (
+ <div className="not-prose my-10 rounded-2xl border-2 border-ink bg-cream p-8 text-center md:p-10">
+ <h2 className="mb-3 text-2xl font-semibold text-ink md:text-3xl">{title}</h2>
+ <p className="mx-auto mb-6 max-w-2xl text-base leading-relaxed text-[#454545] md:text-lg">{description}</p>
+ <PillButton href={buttonHref} size="lg">
+ {buttonText}
+ </PillButton>
+ </div>
+ );
+ }
+ return (
+ <div className="not-prose my-8 rounded-2xl border-2 border-ink bg-cream p-6 md:p-8">
+ <h3 className="mb-2 text-lg font-semibold text-ink">{title}</h3>
+ <p className="mb-4 text-base leading-relaxed text-[#454545]">{description}</p>
+ <PillButton href={buttonHref}>{buttonText}</PillButton>
+ </div>
+ );
+}
+
+export function InlineCTA() {
+ return <BlogCTA variant="inline" />;
+}
diff --git a/site/src/app/cut/blog/_components/BlogGrid.tsx b/site/src/app/cut/blog/_components/BlogGrid.tsx
new file mode 100644
index 00000000..e6e57241
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogGrid.tsx
@@ -0,0 +1,118 @@
+import Link from "next/link";
+
+import { formatBlogDate, titleCaseTag } from "@/app/cut/blog/_components/blogDate";
+import type { BlogPostCard } from "@/lib/blog/read";
+import { blogPath } from "@/lib/blog/keys";
+
+function TagPills({ tags }: { tags: string[] }) {
+ if (tags.length === 0) return null;
+ return (
+ <div className="flex flex-wrap items-center gap-2">
+ {tags.map((tag) => (
+ <span
+ key={tag}
+ className="inline-block rounded-md bg-ink px-2.5 py-1 text-[11px] font-semibold tracking-[0.08em] text-white uppercase"
+ >
+ {titleCaseTag(tag)}
+ </span>
+ ))}
+ </div>
+ );
+}
+
+function FeaturedCard({ post }: { post: BlogPostCard }) {
+ return (
+ <Link href={blogPath(post.slug)} className="group grid gap-6 no-underline lg:grid-cols-2 lg:gap-8">
+ <div className="relative aspect-[2/1] overflow-hidden rounded-2xl border-2 border-ink bg-cream">
+ {post.thumbnailUrl ? (
+ // eslint-disable-next-line @next/next/no-img-element -- pre-encoded AVIF from the media host, not Next-optimizable
+ <img
+ src={post.thumbnailUrl}
+ alt={post.title}
+ width={800}
+ height={500}
+ fetchPriority="high"
+ className="absolute inset-0 h-full w-full object-cover"
+ />
+ ) : null}
+ </div>
+ <div className="flex flex-col justify-center gap-4">
+ <div className="flex flex-wrap items-center gap-x-4 gap-y-2 text-sm text-[#666]">
+ {post.publishedAt ? <time dateTime={post.publishedAt}>{formatBlogDate(post.publishedAt)}</time> : null}
+ <TagPills tags={post.tags} />
+ </div>
+ <h3 className="text-2xl font-semibold leading-tight text-balance text-ink transition-colors group-hover:text-coral md:text-3xl">
+ {post.title}
+ </h3>
+ <p className="text-base leading-relaxed text-[#454545]">{post.excerpt}</p>
+ </div>
+ </Link>
+ );
+}
+
+function PostCard({ post }: { post: BlogPostCard }) {
+ return (
+ <Link
+ href={blogPath(post.slug)}
+ className="group flex flex-col overflow-hidden rounded-2xl border-2 border-ink bg-cream no-underline transition-transform duration-300 hover:-translate-y-1"
+ >
+ <div className="relative aspect-[16/10] overflow-hidden border-b-2 border-ink bg-white">
+ {post.thumbnailUrl ? (
+ // eslint-disable-next-line @next/next/no-img-element -- pre-encoded AVIF from the media host, not Next-optimizable
+ <img
+ src={post.thumbnailUrl}
+ alt={post.title}
+ width={800}
+ height={500}
+ loading="lazy"
+ className="absolute inset-0 h-full w-full object-cover brightness-90 contrast-125 grayscale transition-all duration-500 group-hover:brightness-100 group-hover:contrast-100 group-hover:grayscale-0"
+ />
+ ) : null}
+ </div>
+ <div className="flex flex-1 flex-col p-6">
+ {post.publishedAt ? (
+ <time dateTime={post.publishedAt} className="text-sm text-[#666]">
+ {formatBlogDate(post.publishedAt)}
+ </time>
+ ) : null}
+ <h3 className="my-2 text-xl font-semibold leading-[1.3] text-ink">{post.title}</h3>
+ <p className="line-clamp-3 text-[15px] leading-[1.6] text-[#454545]">{post.excerpt}</p>
+ </div>
+ </Link>
+ );
+}
+
+// The index: the featured post across the top of page one, then the latest
+// posts in a grid.
+export function BlogGrid({ posts, featured }: { posts: BlogPostCard[]; featured: BlogPostCard | null }) {
+ return (
+ <div className="space-y-16">
+ {featured ? <FeaturedCard post={featured} /> : null}
+ <section>
+ <div className="mb-8 flex items-center gap-4">
+ <h2 className="text-sm font-bold tracking-[0.05em] whitespace-nowrap text-ink uppercase">Latest posts</h2>
+ <div className="h-0.5 w-full bg-ink/15" />
+ </div>
+ {posts.length === 0 ? (
+ <p className="text-[#666]">Nothing here yet.</p>
+ ) : (
+ <div className="grid grid-cols-1 gap-6 md:grid-cols-2 md:gap-y-8 lg:grid-cols-3">
+ {posts.map((post) => (
+ <PostCard key={post.id} post={post} />
+ ))}
+ </div>
+ )}
+ </section>
+ </div>
+ );
+}
+
+export function BlogGridSkeleton() {
+ return (
+ <div className="grid grid-cols-1 gap-6 md:grid-cols-2 md:gap-y-8 lg:grid-cols-3" aria-hidden>
+ {Array.from({ length: 6 }, (_, i) => (
+ <div key={i} className="aspect-[4/5] animate-pulse rounded-2xl border-2 border-ink/10 bg-cream" />
+ ))}
+ </div>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogHeaderImage.tsx b/site/src/app/cut/blog/_components/BlogHeaderImage.tsx
new file mode 100644
index 00000000..882dcbfc
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogHeaderImage.tsx
@@ -0,0 +1,19 @@
+// The article's hero: a fixed 240px band the image covers, positioned by the
+// focus the CMS set so the subject stays in frame on every width.
+export function BlogHeaderImage({ src, alt, focus }: { src: string; alt: string; focus: string | null }) {
+ return (
+ <div className="relative mb-6 h-60 w-full overflow-hidden rounded-2xl border-2 border-ink bg-cream md:mb-8">
+ {/* eslint-disable-next-line @next/next/no-img-element -- pre-encoded AVIF from the media host, not Next-optimizable */}
+ <img
+ src={src}
+ alt={alt}
+ width={1600}
+ height={900}
+ fetchPriority="high"
+ className="absolute inset-0 h-full w-full object-cover select-none"
+ style={{ objectPosition: focus ?? "50% 50%" }}
+ draggable={false}
+ />
+ </div>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogIndex.tsx b/site/src/app/cut/blog/_components/BlogIndex.tsx
new file mode 100644
index 00000000..3acf45b6
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogIndex.tsx
@@ -0,0 +1,35 @@
+import { notFound } from "next/navigation";
+
+import { BlogGrid } from "@/app/cut/blog/_components/BlogGrid";
+import { BlogPagination } from "@/app/cut/blog/_components/BlogPagination";
+import { BLOG_PAGE_SIZE, blogPageCount } from "@/lib/blog/keys";
+import { listPublishedPosts } from "@/lib/blog/read";
+
+export const BLOG_INDEX_TITLE = "Blog | Donkey Cut";
+export const BLOG_INDEX_DESCRIPTION =
+ "Notes from building Donkey Cut: video editing techniques, how the editor works, and what changed.";
+
+export function BlogHeading() {
+ return (
+ <div className="mb-8 max-w-[72ch] md:mb-12">
+ <h1 className="text-4xl font-semibold tracking-tight text-ink lg:text-5xl">Blog</h1>
+ <p className="mt-4 text-lg text-[#454545]">Notes on editing video, and on building the editor.</p>
+ </div>
+ );
+}
+
+// One page of the index. The featured post rides page one whatever its date.
+export async function BlogIndex({ page }: { page: number }) {
+ const posts = await listPublishedPosts();
+ const total = blogPageCount(posts.length);
+ if (page < 1 || page > total) notFound();
+ const featured = page === 1 ? (posts.find((post) => post.featured) ?? null) : null;
+ const slice = posts.slice((page - 1) * BLOG_PAGE_SIZE, page * BLOG_PAGE_SIZE);
+ return (
+ <>
+ {featured ? <hr className="mb-8 border-ink/15 md:mb-12" /> : null}
+ <BlogGrid posts={slice} featured={featured} />
+ <BlogPagination current={page} total={total} />
+ </>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogPagination.tsx b/site/src/app/cut/blog/_components/BlogPagination.tsx
new file mode 100644
index 00000000..e08a4420
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogPagination.tsx
@@ -0,0 +1,64 @@
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+import Link from "next/link";
+
+import { blogPageHref } from "@/lib/blog/keys";
+import { cn } from "@/lib/utils";
+
+// The page numbers to show, long runs folded into ellipses.
+export function pageTokens(current: number, total: number): (number | "ellipsis")[] {
+ if (total <= 7) return Array.from({ length: total }, (_, i) => i + 1);
+ const tokens: (number | "ellipsis")[] = [1];
+ const left = Math.max(2, current - 1);
+ const right = Math.min(total - 1, current + 1);
+ if (left > 2) tokens.push("ellipsis");
+ for (let page = left; page <= right; page++) tokens.push(page);
+ if (right < total - 1) tokens.push("ellipsis");
+ tokens.push(total);
+ return tokens;
+}
+
+const link =
+ "inline-flex h-10 min-w-10 items-center justify-center gap-1 rounded-full border-2 px-3 text-sm font-semibold no-underline transition-colors";
+
+function PageLink({ page, active, children }: { page: number; active?: boolean; children: React.ReactNode }) {
+ return (
+ <Link
+ href={blogPageHref(page)}
+ aria-current={active ? "page" : undefined}
+ className={cn(link, active ? "border-ink bg-ink text-white" : "border-transparent text-ink hover:border-ink")}
+ >
+ {children}
+ </Link>
+ );
+}
+
+export function BlogPagination({ current, total }: { current: number; total: number }) {
+ if (total <= 1) return null;
+ return (
+ <nav aria-label="Pagination" className="mt-16 flex flex-wrap items-center justify-center gap-1">
+ {current > 1 ? (
+ <PageLink page={current - 1}>
+ <ChevronLeftIcon className="size-4" />
+ <span className="hidden sm:inline">Previous</span>
+ </PageLink>
+ ) : null}
+ {pageTokens(current, total).map((token, i) =>
+ token === "ellipsis" ? (
+ <span key={`e${i}`} className="px-2 text-[#666]">
+ …
+ </span>
+ ) : (
+ <PageLink key={token} page={token} active={token === current}>
+ {token}
+ </PageLink>
+ ),
+ )}
+ {current < total ? (
+ <PageLink page={current + 1}>
+ <span className="hidden sm:inline">Next</span>
+ <ChevronRightIcon className="size-4" />
+ </PageLink>
+ ) : null}
+ </nav>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogShell.tsx b/site/src/app/cut/blog/_components/BlogShell.tsx
new file mode 100644
index 00000000..f40ddb58
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogShell.tsx
@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+
+import { CutFooter } from "@/app/cut/_components/landing/CutFooter";
+import { CutTopNav } from "@/app/cut/_components/landing/CutTopNav";
+
+// The blog's frame: the site nav and footer on the marketing sand, with one
+// measured column between them.
+export function BlogShell({ children }: { children: ReactNode }) {
+ return (
+ <main className="min-h-screen bg-background font-system text-ink antialiased">
+ <CutTopNav />
+ <div className="px-[clamp(1rem,4vw,4rem)] pt-4 pb-20 md:pt-10 md:pb-28">
+ <div className="mx-auto max-w-[1080px]">{children}</div>
+ </div>
+ <CutFooter />
+ </main>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/BlogVideo.tsx b/site/src/app/cut/blog/_components/BlogVideo.tsx
new file mode 100644
index 00000000..eeeffd42
--- /dev/null
+++ b/site/src/app/cut/blog/_components/BlogVideo.tsx
@@ -0,0 +1,34 @@
+import { parseVideoUrl } from "@/lib/blog/video";
+
+// <Video src="…" /> in an article. A YouTube or Vimeo address becomes its
+// player in a 16:9 frame, a direct file plays in a video element, and an
+// address that is neither stays a link.
+export function BlogVideo({ src, title }: { src: string; title?: string }) {
+ const source = parseVideoUrl(src);
+ if (!source) {
+ return (
+ <p>
+ <a href={src}>{src}</a>
+ </p>
+ );
+ }
+ if (source.kind === "file") {
+ return (
+ <div className="not-prose my-6 overflow-hidden rounded-2xl border-2 border-ink bg-ink">
+ <video src={source.src} controls preload="metadata" playsInline className="block aspect-video w-full" />
+ </div>
+ );
+ }
+ return (
+ <div className="not-prose relative my-6 aspect-video w-full overflow-hidden rounded-2xl border-2 border-ink bg-ink">
+ <iframe
+ src={source.embedSrc}
+ title={title ?? (source.kind === "youtube" ? "YouTube video" : "Vimeo video")}
+ loading="lazy"
+ allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+ allowFullScreen
+ className="absolute inset-0 size-full border-0"
+ />
+ </div>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/HeadingWithAnchor.tsx b/site/src/app/cut/blog/_components/HeadingWithAnchor.tsx
new file mode 100644
index 00000000..9854b3f6
--- /dev/null
+++ b/site/src/app/cut/blog/_components/HeadingWithAnchor.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { Link2 } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { headingId } from "@/lib/blog/headings";
+import { cn } from "@/lib/utils";
+
+const textOf = (node: ReactNode): string => {
+ if (node === null || node === undefined || typeof node === "boolean") return "";
+ if (typeof node === "string" || typeof node === "number") return String(node);
+ if (Array.isArray(node)) return node.map(textOf).join("");
+ if (typeof node === "object" && "props" in node) {
+ return textOf((node.props as { children?: ReactNode }).children);
+ }
+ return "";
+};
+
+// A section heading that is its own anchor: it carries an id from its text,
+// and hovering shows a button that copies the link to it.
+export function HeadingWithAnchor({
+ as: Tag,
+ children,
+ className,
+}: {
+ as: "h2" | "h3";
+ children: ReactNode;
+ className?: string;
+}) {
+ const id = headingId(textOf(children));
+ const copy = () => {
+ const url = `${window.location.origin}${window.location.pathname}#${id}`;
+ void navigator.clipboard.writeText(url);
+ window.history.pushState(null, "", `#${id}`);
+ };
+ return (
+ <Tag id={id || undefined} className={cn("group relative scroll-mt-24", className)}>
+ {children}
+ {id ? (
+ <button
+ type="button"
+ onClick={copy}
+ className="ml-2 inline-flex align-middle opacity-0 transition-opacity group-hover:opacity-100"
+ aria-label="Copy link to section"
+ title="Copy link to section"
+ >
+ <Link2 className="size-4 text-[#666] hover:text-ink" />
+ </button>
+ ) : null}
+ </Tag>
+ );
+}
diff --git a/site/src/app/cut/blog/_components/TableOfContents.tsx b/site/src/app/cut/blog/_components/TableOfContents.tsx
new file mode 100644
index 00000000..a6652218
--- /dev/null
+++ b/site/src/app/cut/blog/_components/TableOfContents.tsx
@@ -0,0 +1,87 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+import type { BlogHeading } from "@/lib/blog/headings";
+import { cn } from "@/lib/utils";
+
+const SCROLL_OFFSET = 100;
+
+// The sticky outline beside an article, from the headings the server read out
+// of the source, with the section in view marked as the reader scrolls.
+export function TableOfContents({ headings }: { headings: BlogHeading[] }) {
+ const [activeId, setActiveId] = useState("");
+ const navRef = useRef<HTMLElement>(null);
+
+ useEffect(() => {
+ const elements = headings
+ .map((heading) => document.getElementById(heading.id))
+ .filter((element): element is HTMLElement => element !== null);
+ const observer = new IntersectionObserver(
+ (entries) => {
+ for (const entry of entries) {
+ if (entry.isIntersecting) setActiveId(entry.target.id);
+ }
+ },
+ { rootMargin: "-120px 0px -60%", threshold: 0 },
+ );
+ for (const element of elements) observer.observe(element);
+ return () => observer.disconnect();
+ }, [headings]);
+
+ useEffect(() => {
+ if (!activeId || !navRef.current) return;
+ navRef.current
+ .querySelector(`a[href="#${CSS.escape(activeId)}"]`)
+ ?.scrollIntoView({ block: "nearest", behavior: "smooth" });
+ }, [activeId]);
+
+ if (headings.length === 0) return null;
+
+ return (
+ <nav
+ ref={navRef}
+ aria-label="On this page"
+ className="sticky top-24 max-h-[calc(100vh-8rem)] w-full overflow-y-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+ >
+ <h3 className="mb-4 text-sm font-semibold text-ink">Overview</h3>
+ <ul className="space-y-2">
+ {headings.map((heading) => (
+ <li key={heading.id} className={cn(heading.level === 3 && "pl-3", heading.id === "faqs" && "mt-3 border-t border-ink/15 pt-3")}>
+ <a
+ href={`#${heading.id}`}
+ className={cn(
+ "block text-sm no-underline",
+ activeId === heading.id ? "font-medium text-ink" : "text-[#666] hover:text-ink",
+ )}
+ onClick={(event) => {
+ event.preventDefault();
+ const element = document.getElementById(heading.id);
+ if (!element) return;
+ setActiveId(heading.id);
+ window.history.pushState(null, "", `#${heading.id}`);
+ const top = element.getBoundingClientRect().top + window.scrollY - SCROLL_OFFSET;
+ window.scrollTo({ top, behavior: "instant" });
+ }}
+ >
+ {heading.text}
+ </a>
+ </li>
+ ))}
+ </ul>
+ </nav>
+ );
+}
+
+// Lands a deep link at its heading with the same offset the outline uses.
+export function ScrollToHash() {
+ useEffect(() => {
+ const id = window.location.hash.slice(1);
+ if (!id) return;
+ const element = document.getElementById(id);
+ if (!element) return;
+ const top = element.getBoundingClientRect().top + window.scrollY - SCROLL_OFFSET;
+ window.scrollTo({ top, behavior: "instant" });
+ }, []);
+ return null;
+}
diff --git a/site/src/app/cut/blog/_components/blogDate.ts b/site/src/app/cut/blog/_components/blogDate.ts
new file mode 100644
index 00000000..94d4374d
--- /dev/null
+++ b/site/src/app/cut/blog/_components/blogDate.ts
@@ -0,0 +1,11 @@
+// Dates on the blog read as "March 29, 2026", in UTC so the server shell and
+// the browser agree.
+export const formatBlogDate = (iso: string) =>
+ new Date(iso).toLocaleDateString("en-US", {
+ year: "numeric",
+ month: "long",
+ day: "numeric",
+ timeZone: "UTC",
+ });
+
+export const titleCaseTag = (tag: string) => tag.charAt(0).toUpperCase() + tag.slice(1);
diff --git a/site/src/app/cut/blog/_components/mdxComponents.tsx b/site/src/app/cut/blog/_components/mdxComponents.tsx
new file mode 100644
index 00000000..ea4dd39b
--- /dev/null
+++ b/site/src/app/cut/blog/_components/mdxComponents.tsx
@@ -0,0 +1,45 @@
+import type { MDXComponents } from "mdx/types";
+import Link from "next/link";
+import type { ComponentPropsWithoutRef } from "react";
+
+import { BlogCTA, InlineCTA } from "@/app/cut/blog/_components/BlogCta";
+import { BlogVideo } from "@/app/cut/blog/_components/BlogVideo";
+import { HeadingWithAnchor } from "@/app/cut/blog/_components/HeadingWithAnchor";
+
+// The typography plugin carries the article; only what prose cannot express
+// is a component here: anchored headings, same-tab internal links, and the
+// blocks an article can place by name.
+export const BLOG_ARTICLE_CLASS =
+ "prose prose-neutral max-w-none prose-headings:font-semibold prose-headings:text-ink prose-headings:tracking-normal prose-h2:mt-10 prose-h2:text-2xl prose-h3:mt-8 prose-h3:text-xl prose-p:leading-[1.7] prose-a:font-semibold prose-a:text-ink prose-strong:text-ink prose-blockquote:border-l-coral prose-blockquote:text-[#454545] prose-code:rounded prose-code:bg-ink/5 prose-code:px-1.5 prose-code:py-0.5 prose-code:font-normal prose-code:before:content-none prose-code:after:content-none prose-pre:rounded-2xl prose-pre:border-2 prose-pre:border-ink prose-pre:bg-ink prose-img:rounded-2xl prose-img:border-2 prose-img:border-ink prose-hr:border-ink/15 prose-th:text-ink";
+
+function Anchor({ href, children, ...props }: ComponentPropsWithoutRef<"a">) {
+ if (href && href.startsWith("/") && !href.startsWith("//")) {
+ return (
+ <Link href={href} {...props}>
+ {children}
+ </Link>
+ );
+ }
+ const external = Boolean(href && /^https?:\/\//.test(href));
+ return (
+ <a href={href} {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})} {...props}>
+ {children}
+ </a>
+ );
+}
+
+export const blogMdxComponents: MDXComponents = {
+ h2: ({ children }) => <HeadingWithAnchor as="h2">{children}</HeadingWithAnchor>,
+ h3: ({ children }) => <HeadingWithAnchor as="h3">{children}</HeadingWithAnchor>,
+ a: Anchor,
+ // eslint-disable-next-line @next/next/no-img-element -- pre-encoded AVIF from the media host, not Next-optimizable
+ img: ({ alt, ...props }) => <img alt={alt ?? ""} loading="lazy" {...props} />,
+ table: ({ children }) => (
+ <div className="overflow-x-auto">
+ <table>{children}</table>
+ </div>
+ ),
+ Video: BlogVideo,
+ BlogCTA,
+ InlineCTA,
+};
diff --git a/site/src/app/cut/blog/page.tsx b/site/src/app/cut/blog/page.tsx
new file mode 100644
index 00000000..43d29e0d
--- /dev/null
+++ b/site/src/app/cut/blog/page.tsx
@@ -0,0 +1,43 @@
+import type { Metadata } from "next";
+import { Suspense } from "react";
+
+import { BlogGridSkeleton } from "@/app/cut/blog/_components/BlogGrid";
+import { BLOG_INDEX_DESCRIPTION, BLOG_INDEX_TITLE, BlogHeading, BlogIndex } from "@/app/cut/blog/_components/BlogIndex";
+import { BlogShell } from "@/app/cut/blog/_components/BlogShell";
+import { DONKEYCUT_CANONICAL } from "@/cut/lib/hosts";
+
+export const metadata: Metadata = {
+ title: BLOG_INDEX_TITLE,
+ description: BLOG_INDEX_DESCRIPTION,
+ alternates: { canonical: `${DONKEYCUT_CANONICAL}/blog` },
+ openGraph: {
+ title: BLOG_INDEX_TITLE,
+ description: BLOG_INDEX_DESCRIPTION,
+ url: `${DONKEYCUT_CANONICAL}/blog`,
+ siteName: "Donkey Cut",
+ type: "website",
+ images: [{ url: "/cut/landing/og.png", width: 1200, height: 630 }],
+ },
+ twitter: {
+ card: "summary_large_image",
+ title: BLOG_INDEX_TITLE,
+ description: BLOG_INDEX_DESCRIPTION,
+ images: ["/cut/landing/og.png"],
+ },
+};
+
+export const instant = true;
+
+// The blog index, served at /blog by the proxy's "/…" → "/cut/…" rewrite. The
+// list is a cached read, so it joins the static shell and refreshes when a
+// post is saved on su.
+export default function BlogIndexPage() {
+ return (
+ <BlogShell>
+ <BlogHeading />
+ <Suspense fallback={<BlogGridSkeleton />}>
+ <BlogIndex page={1} />
+ </Suspense>
+ </BlogShell>
+ );
+}
diff --git a/site/src/app/cut/blog/page/[n]/page.tsx b/site/src/app/cut/blog/page/[n]/page.tsx
new file mode 100644
index 00000000..281fa2e7
--- /dev/null
+++ b/site/src/app/cut/blog/page/[n]/page.tsx
@@ -0,0 +1,57 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+
+import { BlogGridSkeleton } from "@/app/cut/blog/_components/BlogGrid";
+import { BLOG_INDEX_DESCRIPTION, BLOG_INDEX_TITLE, BlogHeading, BlogIndex } from "@/app/cut/blog/_components/BlogIndex";
+import { BlogShell } from "@/app/cut/blog/_components/BlogShell";
+import { DONKEYCUT_CANONICAL } from "@/cut/lib/hosts";
+import { blogPageCount, blogPageHref } from "@/lib/blog/keys";
+import { listPublishedSlugs } from "@/lib/blog/read";
+
+type Params = { params: Promise<{ n: string }> };
+
+// Pages 2 onward; page 1 is /blog itself.
+const parsePage = (value: string) => {
+ const page = Number(value);
+ return Number.isInteger(page) && page >= 2 ? page : null;
+};
+
+// Cache Components needs at least one param; a blog with one page gets a
+// placeholder the page answers with 404.
+export async function generateStaticParams() {
+ const total = blogPageCount((await listPublishedSlugs()).length);
+ const pages = Array.from({ length: Math.max(0, total - 1) }, (_, i) => ({ n: String(i + 2) }));
+ return pages.length > 0 ? pages : [{ n: "0" }];
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+ const page = parsePage((await params).n);
+ if (!page) return {};
+ const title = `${BLOG_INDEX_TITLE} — Page ${page}`;
+ return {
+ title,
+ description: BLOG_INDEX_DESCRIPTION,
+ alternates: { canonical: `${DONKEYCUT_CANONICAL}${blogPageHref(page)}` },
+ openGraph: { title, description: BLOG_INDEX_DESCRIPTION, siteName: "Donkey Cut", type: "website" },
+ };
+}
+
+export const instant = true;
+
+async function PageIndex({ params }: Params) {
+ const page = parsePage((await params).n);
+ if (!page) notFound();
+ return <BlogIndex page={page} />;
+}
+
+export default function BlogPagePage({ params }: Params) {
+ return (
+ <BlogShell>
+ <BlogHeading />
+ <Suspense fallback={<BlogGridSkeleton />}>
+ <PageIndex params={params} />
+ </Suspense>
+ </BlogShell>
+ );
+}
diff --git a/site/src/app/cut/sitemap.ts b/site/src/app/cut/sitemap.ts
index e1cafcf5..cfe6456e 100644
--- a/site/src/app/cut/sitemap.ts
+++ b/site/src/app/cut/sitemap.ts
@@ -1,10 +1,17 @@
import type { MetadataRoute } from "next";
import { DONKEYCUT_CANONICAL } from "@/cut/lib/hosts";
+import { blogPageCount, blogPageHref, blogPath } from "@/lib/blog/keys";
+import { listPublishedPosts } from "@/lib/blog/read";
// Served at donkeycut.com/sitemap.xml via the proxy rewrite (src/proxy.ts).
// The legal pages are canonical on this host, since they describe Donkey Cut.
-export default function sitemap(): MetadataRoute.Sitemap {
+// The blog entries come from the same cached read the index uses, so a
+// publish on su refreshes them; the dates are the rows' own, never the clock,
+// which keeps the route prerenderable.
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+ const posts = await listPublishedPosts();
+ const pages = blogPageCount(posts.length);
return [
{
url: `${DONKEYCUT_CANONICAL}/`,
@@ -16,6 +23,22 @@ export default function sitemap(): MetadataRoute.Sitemap {
changeFrequency: "monthly",
priority: 0.8,
},
+ {
+ url: `${DONKEYCUT_CANONICAL}/blog`,
+ changeFrequency: "weekly",
+ priority: 0.8,
+ },
+ ...Array.from({ length: Math.max(0, pages - 1) }, (_, i) => ({
+ url: `${DONKEYCUT_CANONICAL}${blogPageHref(i + 2)}`,
+ changeFrequency: "weekly" as const,
+ priority: 0.4,
+ })),
+ ...posts.map((post) => ({
+ url: `${DONKEYCUT_CANONICAL}${blogPath(post.slug)}`,
+ lastModified: post.revisedAt ?? post.publishedAt ?? undefined,
+ changeFrequency: "monthly" as const,
+ priority: 0.7,
+ })),
{
url: `${DONKEYCUT_CANONICAL}/privacy`,
changeFrequency: "yearly",