fix(website): output raw MDX for docs markdown

[NathanFlurry]

Motivation

• The site build was stripping MDX/JSX from generated docs which removed content like quickstarts and embedded components.
• The goal is to preserve the original MDX content when producing the static markdown files in public/docs/ so downstream tools and viewers see the unmodified source.

Description

• Removed the MDX-cleaning and H1-stripping logic and now write the original file contents to public/docs/ instead of a cleaned version in website/src/integrations/generate-routes.ts.
• generateMarkdownFiles now emits the raw MDX content (content) into output files instead of cleanContent or stripped fragments.
• Route generation and page metadata extraction via processPage are unchanged, so title/description extraction still uses the AST parsing logic.

Testing

• The lefthook pre-commit hook ran cargo-fmt as part of the commit and completed successfully.

---

Codex Task

[railway-app]

🚅 Deployed to the rivet-pr-3972 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-inspector	❌ Build Failed (View Logs)	Web	Jan 18, 2026 at 11:14 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Jan 18, 2026 at 11:14 pm
website	❌ Build Failed (View Logs)	Web	Jan 18, 2026 at 11:13 pm

[claude]

PR Review: fix(website): output raw MDX for docs markdown

Summary

This PR removes MDX/JSX cleaning logic from the docs generation pipeline, preserving the original MDX content (including imports, JSX components, and embedded content) in the generated markdown files under public/docs/.

Code Quality

Strengths:

• Clean removal of dead code - the cleanMdxContent and stripContentBeforeFirstH1 functions are completely removed
• Simplification is well-executed: reduces complexity by -42 lines with only +1 addition
• The change is focused and does not introduce scope creep
• Preserves existing functionality for route generation and metadata extraction

Potential Issues:

1. Frontmatter preservation - The generated markdown files will now include YAML frontmatter blocks. Depending on what consumes these files, this might be desired behavior if downstream tools parse MDX/frontmatter, or problematic if consumers expect pure markdown without metadata.

2. File extension mismatch - Files are written as .md but contain .mdx content (JSX, imports, components like Card, CardGroup). This could confuse markdown renderers that do not support JSX, tools expecting standard markdown. Consider renaming output files to .mdx for clarity.

Functionality

Questions:

• What tools/systems consume the files in public/docs/? If they are standard markdown parsers, they will fail on JSX components. If they are MDX-aware, the current approach is correct.
• Why generate static files at all if the content is identical to the source? Could consumers read from src/content/docs/ directly?

Edge Cases:

• The code assumes all .mdx files are valid - no error handling for malformed MDX
• Missing validation that JSX components will render correctly in the target environment

Performance

Positive impact:

• Removes regex-heavy processing (cleanMdxContent had 7+ regex operations per file)
• Eliminates AST parsing for content cleaning (only used for metadata now)
• Should see measurable performance improvement during build

Security

No security concerns identified:

• File operations are properly scoped to specific directories
• No user input is directly incorporated into file paths
• Path handling uses path.join which is safe

Testing

Current Coverage:

• PR description mentions lefthook ran successfully (formatting only)
• No functional tests mentioned - this is a behavioral change

Recommendations:

1. Add integration test verifying JSX/import preservation in output
2. Verify output files are correctly consumed by downstream tools
3. Compare before/after output for a sample file to ensure expected behavior

Architecture

Design Questions:

• File extension choice: Should output be .mdx instead of .md to accurately reflect content?
• Purpose clarity: If the output is identical to source, what is the value of this generation step? Consider documenting the use case.

Verdict

Approve with minor suggestions.

The code change is clean and accomplishes the stated goal. The main questions are about the broader architecture and ensuring downstream compatibility. Before merging, I would recommend:

1. Confirming what consumes public/docs/ files and that they handle MDX syntax
2. Adding a test case to prevent regression
3. Considering whether .md or .mdx extension is more appropriate for the output files

The performance improvement from removing regex processing is a nice bonus!

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3972

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3972

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3972

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3972

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3972

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3972

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3972

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3972

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3972

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3972

commit: d756038