[bryant22]

What was wrong on mdx.org.ai

• / redirects to /docs, which showed the Navigation components page instead of the documentation's index.
• The sidebar listed only one page.
• The component tables' links (/Header, /Footer ...) were 404s.
• No favicon, and the old .org.ai logo.

Why, and the fix

• Six files claimed /docs. Folders in parentheses don't add to the address, so the five UI-component groups' index.mdx collided with docs/index.mdx. The group overviews are now <group>-components.mdx.
• The sidebar was empty because the root meta.json named pages inside group folders. Fumadocs drops those, and hides anything not listed. It now lists the four group folders, each with its own meta.json (title, overview first, open by default at the top level).
• 88 internal links were fixed: root-relative links missing /docs, and nested paths such as /docs/structured-data/mdxld that group folders never create. 16 links to pages that don't exist became plain text: @mdxld/extract, @mdxld/jsonld, @mdxld/jsx, and the removed buildercss package.
• Linked headings put a link inside a link, which caused React hydration error #418 on /docs. Each section now ends with "See the … overview." instead.
• New mark and icons: the Org.AI Foundation's mark in the header, inlined so it follows the light and dark themes, plus favicon.ico, icon.svg and a 180 px apple-icon.

Every address that worked before still works.

Checked

Built locally (next build):

• All 101 pages load with no console errors.
• None scrolls sideways at 390 px. One page reports a wider layout only because of Fumadocs' parked mobile drawer; it doesn't actually scroll.

Deploying

Not deployed. The site deploys by hand (cd apps/docs && pnpm deploy), and main may hold other unreleased work, so whoever usually releases it should deploy it.

🤖 Generated with Claude Code

[claude]

Review

I read the PR description, the layout and logo changes, the meta.json files and the shape of the generated diff. I did not build the site or read the roughly 88 link edits in the MDX files one by one.

The diagnosis is clear and the fix matches it: six pages claimed /docs, the sidebar was missing pages, and links pointed at the wrong paths. Keeping every existing URL working is a good constraint.

Things worth addressing

1. Generated files are committed. apps/docs/.source/browser.ts and server.ts are fumadocs-mdx output (about 200 changed lines, mostly reordered imports). That makes the diff noisy and invites merge conflicts.

   • Check whether they are meant to be tracked. If not, add .source to .gitignore and generate it in postinstall/prebuild.
   • If they are tracked on purpose, regenerate them from a clean checkout so the ordering is deterministic.

2. Nothing stops the links breaking again. The PR fixes 88 links by hand and turns 16 into plain text, but adds no test. The repo already keeps guards in test/repo/.

   • A small guard would walk docs/**/*.mdx and check that every internal ](/…) link resolves to a page slug. Folders in parentheses don't count toward the URL.
   • The same guard could assert that no two files map to the same slug. That is the /docs collision that started this.
   • Without it, the next index.mdx added inside a ( ) folder will silently take over /docs.

3. public/org-ai.svg is now unused by the layout. It was rewritten in this PR, but layout.tsx uses the inline OrgAiMark. Check that something else references it (for example metadata or OG tags). If nothing does, delete it. If something does, it carries the same mark and can drift from org-ai-mark.tsx, since the two are maintained separately.

4. Plain-text packages. @mdxld/extract, @mdxld/jsonld and @mdxld/jsx are listed in CLAUDE.md as real packages in this monorepo. Only their docs pages are missing. Plain text is fine for now, but a follow-up issue to write those pages would stop them being forgotten.

Minor

• org-ai-mark.tsx: the amber #f0af66 is hard-coded. It is fine on both themes, but a CSS variable or a comment saying it is intentional would help.
• The rotate(369 …) and rotate(429 …) values on the last two ovals are equivalent to 9° and 69°. This is cosmetic only.
• aria-hidden is correct because the adjacent text names the site. icon.svg and favicon.ico follow the Next.js app-router file convention, so no extra wiring is needed.
• The meta.json files are consistent. Each group lists its overview first and then "...". The root lists the four folders using parenthesised names, which is the right form for fumadocs.

Security and performance

No concerns. The changes are static content and an inline SVG, which also saves a request compared with next/image. There are no new dependencies.

Tests

The PR reports a manual check of 101 pages with no console errors and no horizontal scroll at 390px. That is useful but not repeatable, so item 2 is the main gap.

Overall this is a solid change. I'd merge after resolving item 1 (or confirming it is intended) and ideally adding the link/slug guard.

[claude]

Review

Most of this PR is link, sidebar and routing fixes in docs/, and the approach looks right. I read the group-overview renames, the per-group meta.json files, and the theme, font and CSS changes under apps/docs/app. I didn't build the site or run tests.

Things to look at

1. Description and code disagree on themes. The PR body says the mark follows light and dark themes, but app/layout.tsx sets forcedTheme: 'dark' with enableSystem: false, docs/layout.tsx adds disableThemeSwitch, and global.css gives light and dark identical colours. The site has no light mode. That may be deliberate, but say so in the description. Also check contrast, especially --fd-muted-foreground (about 58% lightness on a 6% background) for small text. Light-mode handling in the inline mark is dead code unless light mode returns.
2. Generated files in the diff. apps/docs/.source/{browser,server}.ts are fumadocs-mdx output (server.ts is +203 lines). If they are meant to be tracked, fine; otherwise gitignore .source to avoid merge conflicts on every docs change.
3. Font weights. .fd-title uses weight 360 and .prose h1 uses 340. This needs publicsans-latin.woff2 to be a variable font covering that range (localFont weight '100 900' assumes it). Please confirm. Only the latin subset ships, so non-Latin text falls back to system fonts.
4. Two mechanisms for heading styles. .fd-title is applied by class and the other headings by .prose hN. Consider one approach.
5. Hand-converted HSL values. They come from oklch tokens, and the comments are the only record. A short note on how to regenerate them would help.

Content and links

• Replacing 16 dead links with plain text is sensible. Open a follow-up to restore them when the pages exist (@mdxld/extract, jsonld, jsx).
• Moving links to a closing 'See the … overview.' line correctly avoids the nested-anchor hydration error (#418).
• 'Every address that worked before still works' is a strong claim. Renaming the group index.mdx files changes their URLs, and no redirects are added. Please verify the old group-overview URLs resolve, or add redirects in next.config.

Tests
No automated tests. A cheap guard would be a CI step running next build plus a link checker (or a script that walks internal links against the page tree). Without it the 88 link fixes can regress silently, and the manual 101-page check won't stay true as docs change.

Security and performance
No concerns. The font is self-hosted with its OFL licence included, the mark is inlined, and the binary assets are small.

Overall this looks good to merge once the theme description and the redirect claim are checked.