Repository navigation
feat(www): step-by-step guides with screenshots and videos, part 1 of 4 - #2428
Merged
Merged
Conversation
scripts/guides/capture.mjs boots the sidecars Electron boots, on a data folder of its own, serves the built renderer, and drives it in Chromium with the Electron bridge stubbed. Each walkthrough writes its screenshots as 2x WebP into public/guides/<slug>/ and records its video in the same run: a drawn pointer and a one-line caption, the screenshot frames cut out, and long waits on a model played faster. upload-videos.mjs puts the videos on Vercel Blob under content-hashed names. The demo documents are public NIST publications, fetched from their source and checked against the sha256 in demo-documents/manifest.json; none is committed. The server walkthrough types a placeholder key and swaps in OPENROUTER_API_KEY on the request, so no key is typed or shown. The plan the maintainer agreed is plans/community-local/tutorials.md.
…s link /docs/v2/guides holds one guide per task, each a video above numbered steps with a screenshot of SurfSense for every step: set up, run a model on your computer, use a server or provider, add files and folders, ask and check citations, choose sources, add web pages and YouTube videos, and workspaces. The hub sits under Overview in the docs sidebar, Tutorials leads the Resources menu and footer, /tutorials redirects to it, and the reference pages point to their guides. GuideVideo plays a guide's video from guide-videos.json, loading nothing until the reader presses play. guides-content.test.ts holds every shot to 250 KB with alt text, every video to the Blob store, and public/guides to pictures a page shows. Quick start described an optional-models step that setup no longer has, and said to click Use after a download, which now makes the model the one in use.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
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 was referenced Nov 10, 2026
upload-videos.mjs put all 27 takes on the site's Blob store, so every guide page now plays its video, and the check that every guide video is hosted passes.
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
The first of the tutorial PRs in
plans/community-local/tutorials.md: eight step-by-step guides on the site, and the tooling that captures them from the real app./docs/v2/guides: set up SurfSense, run a model on your computer, use a model from a server or provider, add files and folders, ask a question and check its citations, choose which sources to use, add web pages and YouTube videos, and workspaces. Each one is a short silent video above numbered steps, with a screenshot of SurfSense for every step (2× WebP, 2.1 MB for all eight).www/scripts/guides/.capture.mjsboots a throwaway SurfSense: the same sidecars Electron boots, on a data folder of its own. It does not useheadless/main.ts, which setsHF_HUB_OFFLINEand the Docker runtime. It drives the built renderer in Chromium with the Electron bridge stubbed. Each walkthrough writes its screenshots and records its video in the same run. The video gets a drawn pointer and a caption line, the screenshot frames are cut out, and model waits are sped up.upload-videos.mjsputs the videos on Vercel Blob under content-hashed names./tutorialsredirects to the hub, and the reference pages (Sources, Chat, Workspaces, Local models, API providers, Quick start) link to their guides.The demo documents are three NIST publications, public domain, fetched and checked against the sha256 in
demo-documents/manifest.json; none is committed. The web guide uses a NIST page and NIST's own CSF 2.0 video. Answers come from Qwen3.8 27B through OpenRouter. The server walkthrough types a placeholder into the key field, and the request that saves the server carriesOPENROUTER_API_KEYinstead, so no key is typed or shown.Why
The maintainer asked for tutorial videos and step-by-step screenshot guides for everything SurfSense does, on the site and in the app. This PR covers getting started, sources and chat. Studio, the agent, plugins, voice, jobs and settings follow in three more site PRs, then the in-app links.
The videos are on the site's Vercel Blob store:
upload-videos.mjsuploaded all 27 takes on 10 Nov 2026 and listed them infeatures/guides/guide-videos.json, so the unit test "every guide video is hosted" passes.Found while capturing:
searxng.surfsense.comanswers with zero results, because every engine behind it reports "Suspended: proxy error". So the search half of Add from the web finds nothing right now. The web guide uses pasted links instead.Fixes # (none: asked in chat)
How to test
cd www && pnpm test:unit: 195 of 196 pass; the one failure is the video upload check above.cd www && pnpm build: passes, and prerenders the hub and the eight guides./docs/v2/guidesand a guide, such as/docs/v2/guides/ask-and-cite.www, withsurfsense_local/frontendbuilt (pnpm translations, thenvite build) andOPENROUTER_API_KEYset:node scripts/guides/capture.mjs --fresh, or name walkthroughs to retake only those. In a worktree, pointGUIDES_RUNTIMES_DIRandGUIDES_MODELS_DIRat a checkout with staged runtimes and bundled models.BLOB_READ_WRITE_TOKEN=… node scripts/guides/upload-videos.mjs.High-level PR Summary
This PR adds eight step-by-step tutorial guides with silent videos and screenshots to the SurfSense website. The guides cover getting started tasks like setup, running models locally, connecting to API providers, adding sources, asking questions, and managing workspaces. Each guide includes a short video and numbered steps with 2× WebP screenshots. The implementation includes sophisticated capture tooling that boots a throwaway SurfSense instance and uses Playwright to automate walkthroughs, recording videos with drawn pointers and captions while capturing screenshots. Videos are uploaded to Vercel Blob storage with content hashing. The guides are accessible from the Resources menu and footer, with cross-links from relevant documentation pages. A minor fix updates the Quick start guide to reflect recent setup flow changes.
⏱️ Estimated Review Time: 30-90 minutes
💡 Review Order Suggestion
plans/community-local/tutorials.mdwww/AGENTS.mdwww/scripts/guides/capture.mjswww/scripts/guides/app/boot-app.mjswww/scripts/guides/app/bridge.mjswww/scripts/guides/capture/walkthrough-session.mjswww/scripts/guides/walkthroughs/index.mjswww/scripts/guides/walkthroughs/set-up.mjswww/scripts/guides/walkthroughs/local-model.mjswww/scripts/guides/walkthroughs/connect-a-server.mjswww/scripts/guides/walkthroughs/add-sources.mjswww/scripts/guides/walkthroughs/ask-and-cite.mjswww/scripts/guides/walkthroughs/pick-sources.mjswww/scripts/guides/walkthroughs/add-from-the-web.mjswww/scripts/guides/walkthroughs/workspaces.mjswww/scripts/guides/walkthroughs/new-chat.mjswww/scripts/guides/walkthroughs/open-settings.mjswww/scripts/guides/demo-documents/fetch-demo-documents.mjswww/scripts/guides/demo-documents/manifest.jsonwww/scripts/guides/media/edit-video.mjswww/scripts/guides/media/png-to-webp.mjswww/scripts/guides/media/run-ffmpeg.mjswww/scripts/guides/page/overlay.mjswww/scripts/guides/upload-videos.mjswww/features/guides/guide-video.tsxwww/features/guides/guide-videos.jsonwww/features/guides/guides-content.test.tswww/content/docs/v2/guides/index.mdxwww/content/docs/v2/guides/meta.jsonwww/content/docs/v2/guides/set-up.mdxwww/content/docs/v2/guides/local-model.mdxwww/content/docs/v2/guides/connect-a-server.mdxwww/content/docs/v2/guides/add-sources.mdxwww/content/docs/v2/guides/ask-and-cite.mdxwww/content/docs/v2/guides/pick-sources.mdxwww/content/docs/v2/guides/add-from-the-web.mdxwww/content/docs/v2/guides/workspaces.mdxwww/content/docs/v2/meta.jsonwww/content/docs/v2/quick-start.mdxwww/content/docs/v2/sources.mdxwww/content/docs/v2/chat.mdxwww/content/docs/v2/workspaces.mdxwww/content/docs/v2/models/local.mdxwww/content/docs/v2/models/api-providers.mdxwww/features/site-navigation/site-navigation.tswww/features/site-navigation/site-navigation.test.tswww/components/site/site-content.tswww/components/ui/icons.tsxwww/mdx-components.tsxwww/next.config.mtswww/features/docs/source.tswww/package.jsonwww/pnpm-lock.yaml.pre-commit-config.yaml