Repository navigation
docs(www): ship the 2.0 user docs and the homepage loading fixes - #2385
Merged
Merged
Conversation
fumadocs-mdx 15 loads next.config only as ESM, so the config becomes next.config.mts: import.meta.dirname replaces __dirname and its local imports name their .ts files. A package-wide "type": "module" was rejected because it breaks tests that read __dirname. zod moves to 4.6.7 to match fumadocs-mdx's own copy; with two copies, tsc ran out of memory comparing them in source.config.ts. 16.17.10 is newer but younger than pnpm's 7-day minimumReleaseAge.
Replaces the "Docs in progress" placeholder at /docs/v2 with guides for the desktop app and its Docker image: install and quick start, using SurfSense, models, plugins, Docker, privacy and license, and reference. Labels are quoted from the app's English catalog.
Each docs page gets Copy Markdown and an Open menu (GitHub, View as Markdown, ChatGPT, Claude, Cursor), adapted from Fumadocs' page actions onto fumadocs-ui's own primitives so no packages are added. A page's Markdown is at its URL plus .mdx, and at its own URL for a request that prefers text/markdown (proxy.ts). /llms.txt lists every page and /llms-full.txt holds them all.
Turbopack's CSS parser doesn't know ::highlight and warned on every compile about the two Fumadocs utilities that style search matches. Tailwind now skips them, and the same rule is a <style> in the root layout's head, which Turbopack doesn't parse. Search looks the same.
next.config.mts imports them; as .ts files in a package without "type": "module", Node parsed them as CommonJS first and printed MODULE_TYPELESS_PACKAGE_JSON on every start. Their tests, a comment and the install-channels doc follow the new names.
fumadocs.dev installs @fumadocs/base-ui under the fumadocs-ui name and uses its Spacious layout; the Radix fumadocs-ui has no Spacious in any release. fumadocs-ui now aliases @fumadocs/base-ui 16.17.8, so existing imports keep working, and the docs layout, page and CSS move to Spacious. The overrides that flattened the old layout go: the fixed grid, the single-colour surfaces and their --main-panel tokens, the custom sidebar separator and the clerk TOC. The copied page actions give way to the built-in Copy Markdown and Open, and pages show their last update.
…ting Set up follows the overview, with the Models folder inside it. Every folder is one level deep: SurfSense's own plugins move up out of their subfolder, under a label, and the old addresses redirect. Models and Plugins split into labelled groups, and pages whose titles leaned on their folder are renamed, such as Docker's index to Install with Docker.
Fumadocs' PageLastUpdate renders the date only after hydration, so the server HTML held "Last updated on" alone, and it accepts no format: it prints the browser's numeric date, where 11/2/2026 reads two ways. The page now renders it on the server as "November 2, 2026", in UTC.
A Fumadocs icon link, styled like the GitHub one; Fumadocs ships no Discord icon, so it takes the site's own mark. DISCORD_URL joins REPO_URL in site-content.
…k for Legacy The 2.0 entry showed a generic book, and Legacy had no icon at all, so Fumadocs drew an "S". Both names join DOCS_ICONS.
CONTRIBUTING and AGENTS covered only docs/architecture, so a change to what users see could leave www/content/docs/v2 describing the old behaviour. Both now ask for the page to change in the same PR, and www/AGENTS.md holds the writing rules the 2.0 docs follow.
The docs were Fumadocs' stock neutral greys while the rest of the site uses the warm canonical palette. Fumadocs' tokens now take PALETTE.css values in light mode, only while a docs page is shown, so its popovers follow. Spacious paints its shell with fd-card and the raised page with fd-background, so those take app-shell and card.
The app shows Plug01Icon for plugins in its sidebar, Settings and the composer; the docs showed Unplug. Legacy's connectors keep Unplug.
Each folder's meta.json listed "index", which Fumadocs ranks above the folder claiming it, so the folders only expanded and their overview sat as the first child. Without it, clicking the folder opens the overview, as fumadocs.dev's folders do, and the overviews take the folder names.
The cached HTML for / came back without .ss-home: SiteShell chose the design from usePathname, which read wrong on the server for the root route. Until hydration the hero sat in an overflow-x-hidden wrapper that clipped its -mt-20 pull-up, so a white band showed under the nav. Every route under (home) is on the site design and /login and /register are gone, so the branch had no routes left. The layout now renders the design directly as a server component, and the page comments that pointed at SITE_DESIGN_ROUTES point at the layout.
The blur placeholder is an SVG filter painted at full width; a gradient of the scene's own sky, haze and ground now stands in instead, so the white copy is readable from the first paint.
The 4344px master made every screen decode a 3840x1280 bitmap, phones included through the 360vw offset, and it stuttered mid-scroll. The scene is now 2172x724 with darker lines that hold up when stretched, a quarter of the pixels. The blur placeholder goes, and content-visibility skips the footer's layout and paint until it nears the screen.
The plugins row showed both logos while the copy listed eight plugins; ten ship, so the count and list now match it.
"Open by pull request" and "code in the public repo" read as written for developers; the point now says every plugin is open source and anyone can add their own MCP server to the registry.
fix(www): load the homepage without a white band or a heavy footer
The proxy ran before next.config's .mdx rewrite, so a .mdx URL that preferred Markdown reached the route with the extension in its slug and 404ed. The proxy now leaves .mdx URLs to that rewrite. /llms-full.txt joins 2.0 and Legacy pages, several with the same title, so each page's heading now carries its URL.
…nd installs - Plugin servers also get saved keys and sign-ins, and may get text from ticked sources; a key a server echoes back reaches the chat. - The tool change check covers descriptions and safety hints only. - Local models and dictation stay local unless a chat uses plugins or a remote model. - The script's apt install is updated by apt; the Docker installer needs its folder after `docker compose down`; restore empties the volume. - Open opens SurfSense's copy; report a crash before restarting. - Warnings for LM Studio and Ollama served to the network.
docs(www): write the SurfSense 2.0 user docs on Fumadocs' Spacious layout
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Caution Review failedThe pull request is closed.
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
devintomain, carrying two pull requests. Website and docs only; the desktop app's code and version (2.3.0) are unchanged.docs(www): write the SurfSense 2.0 user docs on Fumadocs' Spacious layout):/docs/v2gets guides in place of its placeholder: install and quick start, using SurfSense, models, plugins, Docker, privacy and license, and reference..mdx,/llms.txtand/llms-full.txt).README.<locale>.md.fix(www): load the homepage without a white band or a heavy footer):/loads is gone: the(home)layout renders the site design on the server, with nousePathnamecheck.Why
Vercel builds
www.surfsense.comfrommain, so the 2.0 docs and the homepage fixes aren't live until this merges. GitHub showsmain's README, so the Docker rows in the download table aren't visible until then either.No tag, no release build. Merging redeploys the website.
Fixes #
How to test
cd www && pnpm install && pnpm test:unitpasses, andpnpm buildsucceeds./docs/v2shows the new docs, and/llms.txtlists the pages;/shows the hero's blue sky under the nav, never white;README.mdonmainlists the two Docker rows in the download table.High-level PR Summary
This pull request ships the SurfSense 2.0 user documentation and homepage loading fixes to production by merging
devintomain. The user docs replace placeholder content at/docs/v2with comprehensive guides covering installation, models, plugins, Docker, privacy, and reference materials. The docs use Fumadocs 16.17 with the Spacious layout, support Markdown export for AI tools (via.mdxURLs,/llms.txt, and/llms-full.txt), and add a Discord link to the header. Homepage improvements eliminate the white loading band, show gradient placeholders until images load, reduce the footer scene size by 75%, and defer footer rendering until it nears the viewport. All localized READMEs now display Docker install commands in a consistent format with a note block instead of separate code fences.⏱️ Estimated Review Time: 30-90 minutes
💡 Review Order Suggestion
www/content/docs/v2/index.mdxwww/content/docs/v2/meta.jsonwww/content/docs/v2/install.mdxwww/content/docs/v2/quick-start.mdxwww/content/docs/v2/models/index.mdxwww/content/docs/v2/models/local.mdxwww/content/docs/v2/models/api-providers.mdxwww/content/docs/v2/models/chatgpt-plan.mdxwww/content/docs/v2/models/claude-plan.mdxwww/content/docs/v2/models/lm-studio.mdxwww/content/docs/v2/models/ollama.mdxwww/content/docs/v2/models/other-local-servers.mdxwww/content/docs/v2/models/other-models.mdxwww/content/docs/v2/workspaces.mdxwww/content/docs/v2/sources.mdxwww/content/docs/v2/chat.mdxwww/content/docs/v2/agent.mdxwww/content/docs/v2/studio.mdxwww/content/docs/v2/voice.mdxwww/content/docs/v2/plugins/index.mdxwww/content/docs/v2/plugins/surfsense-plugins.mdxwww/content/docs/v2/plugins/third-party.mdxwww/content/docs/v2/plugins/google-search.mdxwww/content/docs/v2/plugins/web-crawl.mdxwww/content/docs/v2/plugins/youtube.mdxwww/content/docs/v2/plugins/reddit.mdxwww/content/docs/v2/plugins/instagram.mdxwww/content/docs/v2/plugins/tiktok.mdxwww/content/docs/v2/plugins/google-maps.mdxwww/content/docs/v2/plugins/amazon.mdxwww/content/docs/v2/plugins/walmart.mdxwww/content/docs/v2/plugins/indeed.mdxwww/content/docs/v2/docker/index.mdxwww/content/docs/v2/docker/configuration.mdxwww/content/docs/v2/docker/access.mdxwww/content/docs/v2/docker/updating.mdxwww/content/docs/v2/docker/differences.mdxwww/content/docs/v2/privacy.mdxwww/content/docs/v2/license.mdxwww/content/docs/v2/data-folder.mdxwww/content/docs/v2/updates.mdxwww/content/docs/v2/languages.mdxwww/content/docs/v2/troubleshooting.mdxwww/features/docs/docs-llms.tswww/features/docs/docs-markdown-path.mtswww/features/docs/docs-markdown-path.test.tswww/app/llms-full.txt/route.tswww/app/llms.txt/route.tswww/app/llms.mdx/docs/[[...slug]]/route.tswww/proxy.tswww/app/(home)/layout.tsxwww/app/(home)/_home/home-content.tswww/app/(home)/_home/home-scene.tsxwww/features/docs/docs-redirects.mtswww/features/docs/docs-redirects.test.tswww/features/docs/source.tswww/app/docs/layout.tsxwww/app/docs/[[...slug]]/page.tsxwww/source.config.tswww/next.config.mtswww/AGENTS.mdwww/package.jsonwww/pnpm-lock.yamlwww/tsconfig.jsonREADME.mdREADME.ar.mdREADME.de.mdREADME.es.mdREADME.fr.mdREADME.hi.mdREADME.ja.mdREADME.ko.mdREADME.pt-BR.mdREADME.ru.mdREADME.zh-CN.mdAGENTS.mdCONTRIBUTING.mddocs/architecture/install-channels.md