The Open Framework for Building Agents
fix(docs): link template README section anchors (#4389)
Colton Paddend97f2a689299
diff --git a/apps/docs/app/[lang]/templates/[slug]/template-readme.tsx b/apps/docs/app/[lang]/templates/[slug]/template-readme.tsxindex 56aabe61a..0ba7033bf 100644--- a/apps/docs/app/[lang]/templates/[slug]/template-readme.tsx+++ b/apps/docs/app/[lang]/templates/[slug]/template-readme.tsx@@ -4,7 +4,11 @@ import { createCodePlugin } from "@streamdown/code";import { geistShikiTheme } from "@vercel/geistdocs/shiki-theme";import { useMemo } from "react";import { type Components, defaultRemarkPlugins, Streamdown } from "streamdown";-import { createResolveReadmeLinksPlugin, resolveReadmeHref } from "@/lib/templates/readme-links";+import {+ createReadmeHeadingIdsPlugin,+ createResolveReadmeLinksPlugin,+ resolveReadmeHref,+} from "@/lib/templates/readme-links";interface TemplateReadmeProps {readme: string;@@ -19,12 +23,17 @@ export const TemplateReadme = ({ readme, sourceRevisionHref }: TemplateReadmeProconst remarkPlugins = useMemo(() => [...Object.values(defaultRemarkPlugins),+ createReadmeHeadingIdsPlugin(),createResolveReadmeLinksPlugin(sourceRevisionHref),],[sourceRevisionHref],);const components = useMemo<Partial<Components>>(() => ({+ div: (props) => {+ const { align: _align, ...htmlProps } = props as typeof props & { align?: string };+ return <div {...htmlProps} className="text-left" />;+ },a: ({ href, ...props }) => {const resolvedHref = resolveReadmeHref(href, sourceRevisionHref);if (!resolvedHref) {@@ -40,17 +49,25 @@ export const TemplateReadme = ({ readme, sourceRevisionHref }: TemplateReadmePro/>);},- h1: ({ children }) => (- <h2 className="mt-10 mb-4 text-heading-32 text-gray-1000 first:mt-0">{children}</h2>+ h1: ({ children, ...props }) => (+ <h2 {...props} className="mt-10 mb-4 text-heading-32 text-gray-1000 first:mt-0">+ {children}+ </h2>),- h2: ({ children }) => (- <h3 className="mt-8 mb-3 text-heading-24 text-gray-1000">{children}</h3>+ h2: ({ children, ...props }) => (+ <h3 {...props} className="mt-8 mb-3 text-heading-24 text-gray-1000">+ {children}+ </h3>),- h3: ({ children }) => (- <h4 className="mt-6 mb-3 text-heading-20 text-gray-1000">{children}</h4>+ h3: ({ children, ...props }) => (+ <h4 {...props} className="mt-6 mb-3 text-heading-20 text-gray-1000">+ {children}+ </h4>),- h4: ({ children }) => (- <h5 className="mt-6 mb-3 text-heading-16 text-gray-1000">{children}</h5>+ h4: ({ children, ...props }) => (+ <h5 {...props} className="mt-6 mb-3 text-heading-16 text-gray-1000">+ {children}+ </h5>),}),[sourceRevisionHref],diff --git a/apps/docs/lib/templates/readme-links.test.ts b/apps/docs/lib/templates/readme-links.test.tsindex ede73fab7..b22d38ba4 100644--- a/apps/docs/lib/templates/readme-links.test.ts+++ b/apps/docs/lib/templates/readme-links.test.ts@@ -1,6 +1,7 @@import { describe, expect, it } from "vitest";import {+ createReadmeHeadingIdsPlugin,createResolveReadmeLinksPlugin,resolveReadmeHref,sanitizeReadmeHref,@@ -22,8 +23,8 @@ describe("resolveReadmeHref", () => {);});- it("preserves page anchors and safe absolute links", () => {- expect(resolveReadmeHref("#quick-start", sourceRevisionHref)).toBe("#quick-start");+ it("targets rendered heading IDs and preserves safe absolute links", () => {+ expect(resolveReadmeHref("#quick-start", sourceRevisionHref)).toBe("#user-content-quick-start");expect(resolveReadmeHref("https://eve.dev/docs", sourceRevisionHref)).toBe("https://eve.dev/docs",);@@ -34,6 +35,33 @@ describe("resolveReadmeHref", () => {});});+describe("createReadmeHeadingIdsPlugin", () => {+ it("adds GitHub-compatible heading IDs, including duplicate headings", () => {+ const tree = {+ type: "root",+ children: [+ {+ type: "heading",+ depth: 2,+ children: [{ type: "text", value: "Link wallet" }],+ },+ { type: "heading", depth: 3, children: [{ type: "text", value: "Link wallet" }] },+ { type: "heading", depth: 3, children: [{ type: "text", value: "Link wallet-1" }] },+ { type: "heading", depth: 3, children: [{ type: "text", value: "Node.js" }] },+ { type: "heading", depth: 3, children: [{ type: "text", value: "Next.js setup" }] },+ ],+ };++ createReadmeHeadingIdsPlugin()()(tree);++ expect(tree.children[0]).toHaveProperty("data.hProperties.id", "link-wallet");+ expect(tree.children[1]).toHaveProperty("data.hProperties.id", "link-wallet-1");+ expect(tree.children[2]).toHaveProperty("data.hProperties.id", "link-wallet-1-1");+ expect(tree.children[3]).toHaveProperty("data.hProperties.id", "nodejs");+ expect(tree.children[4]).toHaveProperty("data.hProperties.id", "nextjs-setup");+ });+});+describe("createResolveReadmeLinksPlugin", () => {it("resolves links before the markdown renderer sanitizes relative URLs", () => {const tree = {diff --git a/apps/docs/lib/templates/readme-links.ts b/apps/docs/lib/templates/readme-links.tsindex e06370411..e6ef60ecb 100644--- a/apps/docs/lib/templates/readme-links.ts+++ b/apps/docs/lib/templates/readme-links.ts@@ -3,7 +3,9 @@ const SAFE_ABSOLUTE_PROTOCOLS = new Set(["http:", "https:", "mailto:", "tel:"]);interface MarkdownNode {type?: unknown;url?: unknown;+ value?: unknown;children?: unknown;+ data?: { hProperties?: Record<string, unknown> };}export const createResolveReadmeLinksPlugin =@@ -13,14 +15,24 @@ export const createResolveReadmeLinksPlugin =resolveMarkdownLinks(tree, sourceRevisionHref);};+export const createReadmeHeadingIdsPlugin =+ () =>+ () =>+ (tree: unknown): void => {+ addHeadingIds(tree);+ };+export const resolveReadmeHref = (href: string | undefined,sourceRevisionHref: string,): string | undefined => {const sanitizedHref = sanitizeReadmeHref(href);- if (!sanitizedHref || sanitizedHref.startsWith("#") || isAbsoluteHref(sanitizedHref)) {+ if (!sanitizedHref || isAbsoluteHref(sanitizedHref)) {return sanitizedHref;}+ if (sanitizedHref.startsWith("#")) {+ return `#user-content-${sanitizedHref.slice(1)}`;+ }const bases = getGitHubBases(sourceRevisionHref);if (!bases) {@@ -85,6 +97,46 @@ const getGitHubBases = (};};+const addHeadingIds = (value: unknown): void => {+ const usedSlugs = new Set<string>();+ const visit = (nodeValue: unknown): void => {+ if (!nodeValue || typeof nodeValue !== "object") return;++ const node = nodeValue as MarkdownNode;+ if (typeof node.type === "string" && /^heading$/.test(node.type)) {+ const base = slugHeading(collectText(node));+ let slug = base;+ let suffix = 0;+ while (usedSlugs.has(slug)) slug = `${base}-${++suffix}`;+ usedSlugs.add(slug);+ node.data = {+ ...node.data,+ hProperties: {+ ...node.data?.hProperties,+ id: slug,+ },+ };+ }++ if (Array.isArray(node.children)) {+ for (const child of node.children) visit(child);+ }+ };+ visit(value);+};++const collectText = (node: MarkdownNode): string => {+ if (typeof node.value === "string") return node.value;+ if (!Array.isArray(node.children)) return "";+ return node.children.map((child) => collectText(child as MarkdownNode)).join("");+};++const GITHUB_SLUG_REMOVE =+ /[^\p{L}\p{N}\p{M}\p{Pc}\u0300-\u036f\u1ab0-\u1aff\u1dc0-\u1dff\u20d0-\u20ff\ufe20-\ufe2f -]/gu;++const slugHeading = (value: string): string =>+ value.toLowerCase().replace(GITHUB_SLUG_REMOVE, "").replace(/ /g, "-");+const resolveMarkdownLinks = (value: unknown, sourceRevisionHref: string): void => {if (!value || typeof value !== "object") {return;