Create custom documentation framework #2919

tg339 · 2025-10-29T18:44:14Z

Note

Introduce a new Next.js docs app with TS/Python content, Pagefind search, PostHog analytics, llms.txt generation, and code-snippet testing.

Docs App (Next.js 15)
- New app apps/framework-docs-v2 with TypeScript setup, Tailwind, shadcn/ui, and file-based markdown content in content/{typescript,python}.
- Language-specific routes: /typescript/*, /python/* with layouts, dynamic pages, breadcrumbs, TOC, and side nav.
Search
- Pagefind integration: search UI, Cmd/Ctrl+K shortcut, lazy loader, and post-build indexing (public/pagefind).
Analytics
- PostHog client with custom wrapper; tracks page views, navigation, code copy, and search; proxy rewrites in next.config.{js,ts}.
AI Output
- GET /api/llms.txt?lang=typescript|python to generate language-specific llms.txt from markdown.
Developer Tooling
- Snippet testing utilities (src/lib/snippet-tester.ts) and script scripts/test-snippets.ts with Turbo task test:snippets.
- Content migration script scripts/migrate-content.ts to split MDX into TS/PY markdown.
Config/Infra
- Tailwind, PostCSS, ESLint, sitemap config; turbo.json env additions; package.json scripts for build/indexing.
- Initial example docs (index.mdx, quickstart.md) for both languages.

^{Written by Cursor Bugbot for commit 3913799. This will update automatically on new commits. Configure here.}

vercel · 2025-10-29T18:44:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
framework-docs	Error			Oct 29, 2025 6:44pm

apps/framework-docs-v2/src/components/navigation/TopNav.tsx

+
+  return (
+    <div className="flex items-center gap-1 rounded-md border p-1">
+      <Link href={getOtherLanguageUrl().replace("/typescript", "/typescript")}>


The best way to fix this problem is to remove the meaningless call to .replace("/typescript", "/typescript") (and similarly, .replace("/python", "/python") on line 122). These calls do not alter the string, and their presence reduces code clarity. Instead, getOtherLanguageUrl() is properly responsible for returning the URL for the other language, and we should use it directly as the href for each <Link>. Thus, in this file, lines where unnecessary self-replacement occurs (lines 113 and 122) should be replaced with direct usage of getOtherLanguageUrl(). No new imports or methods are needed.

apps/framework-docs-v2/src/components/navigation/TopNav.tsx

+          TypeScript
+        </Button>
+      </Link>
+      <Link href={getOtherLanguageUrl().replace("/python", "/python")}>


To fix the problem, we should ensure that each language switcher button links to the correct language. The logic already computes getOtherLanguageUrl(), which switches the slug based on the current language. The subsequent calls to .replace("/typescript", "/typescript") and .replace("/python", "/python") are ineffective and unnecessary, possibly left over from a previous implementation. The correct approach is to link directly to the output of getOtherLanguageUrl(), since it returns the right URL for switching between TypeScript and Python.

Therefore, in both link components (lines 113 and 122), simply remove the redundant .replace(...) calls and use getOtherLanguageUrl() directly. No additional method definitions or imports are necessary, and no change to surrounding logic is needed.

apps/framework-docs-v2/src/components/navigation/side-nav.tsx

+
+  return (
+    <Link
+      href={href}


To address the vulnerability, all data used in a URL path (slug) must be sanitized before use. The best way is to encode or sanitize item.slug so that only valid, safe path and URL characters are present. This can be achieved by encoding the slug with encodeURIComponent before using it as a path segment in the href.

Specifically, in apps/framework-docs-v2/src/components/navigation/side-nav.tsx in the NavItemComponent, update the line where href is constructed to encode item.slug using encodeURIComponent. All usages of slugs in URLs should undergo the same process. Imports are not needed for encodeURIComponent.

apps/framework-docs-v2/src/lib/analytics.ts

apps/framework-docs-v2/src/lib/llms-generator.ts

+  cleaned = cleaned.replace(/<\/[A-Z][A-Za-z0-9]*>/g, "");
+
+  // Remove HTML comments
+  cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, "");


To robustly remove HTML comments in a way that prevents incomplete multi-character replacement, we should apply the regular expression replacement repeatedly until no further replacements can occur. This catches cases where removing one comment exposes another, or when constructs can be manipulated by attackers to evade a single-pass replacement. Edit the cleanContent function in apps/framework-docs-v2/src/lib/llms-generator.ts, replacing line 107 (the HTML comment removal) with a loop that continues replacing until the string stabilizes. No additional dependencies are required; vanilla JS suffices for this fix.

cursor · 2025-10-29T18:48:05Z

apps/framework-docs-v2/src/components/navigation/TopNav.tsx

+          TypeScript
+        </Button>
+      </Link>
+      <Link href={getOtherLanguageUrl().replace("/python", "/python")}>


Bug: Redundant URL Replacement Causes Language Switch Error

The LanguageSwitcher component's links use getOtherLanguageUrl() followed by redundant no-op .replace() calls. Since getOtherLanguageUrl() already returns the URL for the opposite language, this causes one of the language buttons to navigate to the wrong language.

cursor · 2025-10-29T18:48:05Z

apps/framework-docs-v2/src/components/navigation/side-nav.tsx

+  const isActive = pathname === href;
+  const hasChildren = item.children && item.children.length > 0;
+  const [isOpen, setIsOpen] = useState(
+    isActive || (hasChildren && item.children?.some((child) => pathname.includes(child.slug))),


Bug: String Property Used as Array

The NavItem.slug property is defined as a string, but the code attempts to call .join("/") on it when generating component keys and navigation hrefs. This will cause a runtime error.

Additional Locations (1)

apps/framework-docs-v2/src/components/navigation/SideNav.tsx#L21-L42

cursor · 2025-10-29T18:48:06Z

apps/framework-docs-v2/src/app/typescript/llms.txt/route.ts

+import { redirect } from "next/navigation";
+
+export async function GET() {
+  redirect("/api/llms.txt?language=typescript");


Bug: Query Parameter Mismatch in API Redirects

The redirects for llms.txt in both TypeScript and Python use language as a query parameter. The /api/llms.txt endpoint, however, expects the lang parameter. This mismatch means the API does not correctly receive the intended language.

Additional Locations (1)

apps/framework-docs-v2/src/app/python/llms.txt/route.ts#L3-L4

Create custom documentation framework

3913799

github-advanced-security bot found potential problems Oct 29, 2025

View reviewed changes

cursor bot reviewed Oct 29, 2025

View reviewed changes

@@ -110,7 +110,7 @@
               return (
                 <div className="flex items-center gap-1 rounded-md border p-1">
-                  <Link href={getOtherLanguageUrl().replace("/typescript", "/typescript")}>
+                  <Link href={getOtherLanguageUrl()}>
                     <Button
                       variant={currentLanguage === "typescript" ? "secondary" : "ghost"}
                       size="sm"
@@ -119,7 +119,7 @@
                       TypeScript
                     </Button>
                   </Link>
-                  <Link href={getOtherLanguageUrl().replace("/python", "/python")}>
+                  <Link href={getOtherLanguageUrl()}>
                     <Button
                       variant={currentLanguage === "python" ? "secondary" : "ghost"}
                       size="sm"

@@ -110,7 +110,7 @@
               return (
                 <div className="flex items-center gap-1 rounded-md border p-1">
-                  <Link href={getOtherLanguageUrl().replace("/typescript", "/typescript")}>
+                  <Link href={getOtherLanguageUrl()}>
                     <Button
                       variant={currentLanguage === "typescript" ? "secondary" : "ghost"}
                       size="sm"
@@ -119,7 +119,7 @@
                       TypeScript
                     </Button>
                   </Link>
-                  <Link href={getOtherLanguageUrl().replace("/python", "/python")}>
+                  <Link href={getOtherLanguageUrl()}>
                     <Button
                       variant={currentLanguage === "python" ? "secondary" : "ghost"}
                       size="sm"

@@ -37,7 +37,7 @@
               level?: number;
             }) {
               const pathname = usePathname();
-              const href = `/${language}/${item.slug}`;
+              const href = `/${language}/${encodeURIComponent(item.slug)}`;
               const isActive = pathname === href;
               const hasChildren = item.children && item.children.length > 0;
               const [isOpen, setIsOpen] = useState(

@@ -104,7 +104,12 @@
               cleaned = cleaned.replace(/<\/[A-Z][A-Za-z0-9]*>/g, "");
               // Remove HTML comments
-              cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, "");
+              // Repeatedly remove HTML comments until none are left (prevents incomplete sanitization)
+              let prev;
+              do {
+                prev = cleaned;
+                cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, "");
+              } while (cleaned !== prev);
               // Clean up excessive whitespace
               cleaned = cleaned.replace(/\n{3,}/g, "\n\n");

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Create custom documentation framework #2919

Create custom documentation framework #2919

Uh oh!

tg339 commented Oct 29, 2025 •

edited by cursor bot

Loading

Uh oh!

vercel bot commented Oct 29, 2025

Uh oh!

Check warning

Copilot Autofix

Check warning

Copilot Autofix

Check failure

Copilot Autofix

Uh oh!

Check failure

Copilot Autofix

cursor bot Oct 29, 2025

Uh oh!

cursor bot Oct 29, 2025

Uh oh!

cursor bot Oct 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Create custom documentation framework #2919

Are you sure you want to change the base?

Create custom documentation framework #2919

Uh oh!

Conversation

tg339 commented Oct 29, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Oct 29, 2025

Uh oh!

Check warning

Copilot Autofix

Check warning

Copilot Autofix

Check failure

Uh oh!

Copilot Autofix

Uh oh!

Check failure

Uh oh!

Copilot Autofix

cursor bot Oct 29, 2025

Choose a reason for hiding this comment

Bug: Redundant URL Replacement Causes Language Switch Error

Uh oh!

cursor bot Oct 29, 2025

Choose a reason for hiding this comment

Bug: String Property Used as Array

Uh oh!

cursor bot Oct 29, 2025

Choose a reason for hiding this comment

Bug: Query Parameter Mismatch in API Redirects

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tg339 commented Oct 29, 2025 •

edited by cursor bot

Loading