Skip to content

armgit / eve

Public Imported from GitHub
0

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.tsx
index 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 }: TemplateReadmePro
const 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.ts
index 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.ts
index 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;