Versioning

import { defineContent, z } from "fromsrc";

const versions = ["v2", "v1"] as const;

type Version = (typeof versions)[number];

export function createVersionedContent(version: Version) {
  return defineContent({
    dir: `docs/${version}`,
    schema: z.object({
      title: z.string(),
      description: z.string().optional(),
      order: z.number().optional(),
    }),
  });
}

"use client";

import { useRouter, usePathname } from "next/navigation";

const versions = ["v2", "v1"];

export function VersionSwitcher() {
  const router = useRouter();
  const pathname = usePathname();

  const currentVersion =
    versions.find((v) => pathname.includes(`/docs/${v}`)) || versions[0];

  const switchVersion = (version: string) => {
    const newPath = pathname.replace(
      `/docs/${currentVersion}`,
      `/docs/${version}`
    );
    router.push(newPath);
  };

  return (
    <select
      value={currentVersion}
      onChange={(e) => switchVersion(e.target.value)}
      className="bg-surface border border-line rounded px-2 py-1 text-sm"
    >
      {versions.map((v) => (
        <option key={v} value={v}>
          {v}
        </option>
      ))}
    </select>
  );
}

---
title: create user
description: create a new user
version: 2026-01-01
---

const schema = extendSchema({
  version: z.string(),
  deprecated: z.boolean().optional(),
  replacement: z.string().optional(),
});

function DeprecationBanner({ doc }) {
  if (!doc.data.deprecated) return null;

  return (
    <Callout type="warning">
      this endpoint is deprecated.
      {doc.data.replacement && (
        <>
          {" "}
          use <Link href={doc.data.replacement}>the new version</Link>.
        </>
      )}
    </Callout>
  );
}