Use Fumadocs' own layout for the docs shell by sdserranog · Pull Request #1253 · ArcadeAI/docs

sdserranog · 2026-10-20T01:46:47Z

What this is

This is the first of three follow-ups to #1250. The goal is to drop the Nextra copies and use Fumadocs' own UI with the Arcade style.

This PR replaces the page shell: the navbar, sidebar, table of contents, breadcrumb, previous/next links and the area under the page. These were a 2,100-line copy of Nextra's theme. They are now Fumadocs' notebook layout and docs page.

The content components (callouts, tabs, steps, code blocks) are not touched here. They come in the next PR, which is also when the page title and the headings get the same type scale.

Preview: https://docs-git-fumadocs-native-shell-arcade-ai.vercel.app

Before and after

Pink numbers mark what changed. The same number points at the same thing on both sides. Everything that isn't marked is unchanged.

A docs page

The end of a page

A toolkit page

Search

Same index, same results, in Fumadocs' dialog.

Video · Screenshot

Table of contents while scrolling

The new table of contents marks where the reader is.

Video

Phones

Fumadocs adds an "On this page" bar on phones. Production has no table of contents there.

Video · Screenshot

The menu opens from the side. Sign Up and Dashboard move into it.

Video · Screenshot

Light mode and the 404 page

Nothing marked: the content is the same, only the shell around it changed.

How it was done

app/en/layout.tsx uses Fumadocs' DocsLayout (notebook). The navbar options are in lib/layout.shared.tsx.
app/en/[[...slug]]/page.tsx uses Fumadocs' DocsPage, DocsTitle and page actions.
Previous/next skip cross links, toolkit pages and external links, the same rule as before (lib/page-neighbours.ts, with a test).
Search is built from Fumadocs' dialog parts, with a small client that reads the DocSearch index (components/algolia-search.tsx).
The crawler config skips the previous/next cards and the "Last updated" line. Merging syncs it to the live crawler.
components/chrome/ and the shell CSS are deleted. The Nextra content CSS stays until the next PR.

What we checked so nothing broke

Every page in the sitemap (303): title, description, social share tags, canonical link and H1 are identical to production.
robots.txt and llms.txt: byte-for-byte identical.
Search: the same query gives the same results, in the same order, as production.
Previous/next: checked on pages next to cross links, the Changelog link and toolkit pages (Gmail still goes to Nimble).
Screens: desktop and phone, dark and light, plus a guide, a quickstart, a toolkit page and the 404 page.
Repo checks: lint, typecheck, build and 908 tests pass.

The recordings caught four bugs, now fixed in this PR:

Stray credit line: "Search powered by Algolia" showed at the top of every page.
Raw search results: results showed whole text blocks as Markdown.
Sidebar over the navbar: at the end of a page, the sidebar slid over the navbar.
Hidden headings on phones: jumping to a heading left it under the "On this page" bar.

Bugbot's review caught three more, also fixed and checked in a browser:

Toolkit Copy Markdown: "Copy Markdown" and "View as Markdown" on toolkit pages got the toolkit JSON. They now ask for ?format=markdown.
Escaped characters in search: results showed <token> and Q&A. They now show <token> and Q&A.
Phone scroll offset: pages without the "On this page" bar (toolkit pages, the home page) no longer leave room for it.

Not in this PR

Content components: callouts, tabs, steps, cards, code blocks and headings move to Fumadocs in the next PR.
Arcade theme: colours and fonts from the brand come after that.
Production-only widget: the PostHog "Feedback" tab only loads on docs.arcade.dev, so it is hidden in the screenshots.

🤖 Generated with Claude Code

The navbar, sidebar, table of contents, breadcrumb and previous/next links were a copy of Nextra's theme. They are now Fumadocs' notebook layout and docs page, so the shell gets Fumadocs' mobile menu, theme switch, table-of-contents popover and page actions. - Search keeps the Algolia index. Its hits are shown in Fumadocs' search dialog, reshaped from DocSearch records. - Previous/next skip link-only entries (cross links, toolkit pages, external links), as before. Toolkit pages keep their own breadcrumb and tool panel; the page leaves room for the panel. - The crawler skips the previous/next cards and the "Last updated" line, which are inside the article. - The 404 page uses Fumadocs' home layout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel · 2026-10-20T01:46:53Z

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 20, 2026 2:22pm UTC

sdserranog · 2026-10-20T01:48:07Z

Closing for now: reviewing this locally first.

cursor

Stale Bugbot comment from a previous run.

Fumadocs' Algolia client expects its own record format, so hits from the DocSearch index came back as whole text blocks rendered as Markdown, and its dialog renders the Algolia credit outside the dialog, where it shows on every page. The dialog is now built from Fumadocs' search parts with a small DocSearch client: short snippets, the section path of each hit, and plain text with the matches highlighted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The highlight rule now targets the Fumadocs search dialog. The rules for the old InstantSearch classes are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cursor

Stale Bugbot comment from a previous run.

The footer band pushes the sticky sidebar up at the end of a page, and the sidebar (layer 20) slid over the navbar (layer 10). The navbar is now above it and opaque. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Below xl the "On this page" bar sits under the navbar, so the anchor offset grows from 5rem to 7.5rem there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0313ba9. Configure here.}

…fset - Toolkit pages: "Copy Markdown" and "View as Markdown" request the page with `?format=markdown`. Fumadocs' actions cannot send `Accept: text/markdown`, so they were getting the toolkit JSON. - Search: decode the HTML entities Algolia adds to highlighted text, so `&`, `<` and `>` show as themselves instead of `&`, `<` and `>`. - Phones: only leave room for the "On this page" bar on pages that have it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview October 20, 2026 01:47

View deployment

sdserranog closed this Oct 20, 2026

sdserranog deleted the fumadocs-native-shell branch October 20, 2026 01:48

sdserranog restored the fumadocs-native-shell branch October 20, 2026 01:48

sdserranog reopened this Oct 20, 2026

cursor Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread app/en/[[...slug]]/page.tsx

vercel Bot deployed to Preview October 20, 2026 02:00

View deployment

Use the brand highlight for search matches

8da074a

The highlight rule now targets the Fumadocs search dialog. The rules for the old InstantSearch classes are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview October 20, 2026 02:02

View deployment

cursor Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread components/algolia-search.tsx

Keep the navbar above the sidebar at the end of a page

2e6abe6

The footer band pushes the sticky sidebar up at the end of a page, and the sidebar (layer 20) slid over the navbar (layer 10). The navbar is now above it and opaque. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview October 20, 2026 02:09

View deployment

Leave room for the phone table of contents bar when jumping to a heading

0313ba9

Below xl the "On this page" bar sits under the navbar, so the anchor offset grows from 5rem to 7.5rem there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview October 20, 2026 02:15

View deployment

cursor Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread app/global.css

vercel Bot deployed to Preview October 20, 2026 14:22

View deployment

sdserranog mentioned this pull request Oct 20, 2026

Use Fumadocs' own content components #1254

Open

sdserranog marked this pull request as ready for review October 20, 2026 19:24

Navigation Menu

Repository navigation

Use Fumadocs' own layout for the docs shell - #1253

Use Fumadocs' own layout for the docs shell#1253
sdserranog wants to merge 6 commits into
mainfrom
fumadocs-native-shell

sdserranog commented Oct 20, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

sdserranog commented Oct 20, 2026

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

sdserranog commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this is

Before and after

A docs page

The end of a page

A toolkit page

Search

Table of contents while scrolling

Phones

Light mode and the 404 page

How it was done

What we checked so nothing broke

Not in this PR

Uh oh!

vercel Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sdserranog commented Oct 20, 2026

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sdserranog commented Oct 20, 2026 •

edited

Loading

vercel Bot commented Oct 20, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading