feat(ui): link to the documentation site from the plugin - #458
Merged
Conversation
The docs live in s2b-dev/site and the README points at seven of its pages, but the plugin itself linked to the site zero times. Every outbound link in src/ went somewhere else: provider vendor key pages, GitHub issues, and skillsmp.com. manifest.json sets authorUrl, but Obsidian only uses that to linkify the author *name* in the community-plugin modal, and there is no helpUrl field (QuickAdd ships one; the app ignores it) — so a user stuck inside the plugin had exactly one escalation path: open a GitHub issue. Add links on the six surfaces where someone is either stuck or facing a concept that inline copy cannot carry: - Troubleshooting settings: a "Troubleshooting guide" row above the GitHub row, which is reworded to "Still stuck?" so docs read as the first stop. The site page is organised by symptom, so it deflects most of what would otherwise arrive as an issue. - General settings: help icon on "Note access policy" — two vault modes crossed with per-provider trust, where one toggle inverts meaning. - Onboarding footer: a quiet link beside Skip, the one screen every user sees. - Provider setup picker: the setup guide covers local Ollama and model choice. - Agent editor: Core skills, Integrations, and MCP servers. - Add skill modal: the format an imported SKILL.md has to satisfy. URLs live in one map (src/utils/docs.ts) rather than inline at call sites. The site's routes have already moved once — its astro.config.mjs still carries redirects for the stale links the README had scattered — so the next restructure should be a one-file reconciliation. Rendering goes through DocsLink.svelte: an icon variant for setting rows (via SettingItem's existing nameSuffix snippet) and an inline variant for section descriptions. Plain anchors, no platform branching: Obsidian hands external _blank links to the system browser on desktop and mobile alike, so these need none of the window.open workarounds the OAuth flow does. The onboarding footer's mobile rule had to be rewritten from `.s2b-onboarding-footer > button` to match through the new wrapper: `display: contents` removes the wrapper from layout but not from the DOM tree a child combinator walks, so the old selector would have stopped matching and Skip would have lost its quiet styling. Verified under real mobile emulation.
Contributor
Greptile SummaryThe PR centralizes documentation URLs and adds reusable anchor-based documentation controls across onboarding, provider setup, agent configuration, skills, and settings.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains; the previously reported mobile documentation path no longer calls window.open, and its surrounding components do not intercept normal anchor activation. Important Files Changed
Reviews (3): Last reviewed commit: "fix(ui): open the remaining external lin..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
…utton Greptile caught a real P1: `openDocs` wrapped `window.open`, which Obsidian's iOS WKWebView returns null for unconditionally (confirmed on-device, per the note on navigateToAuthorizeUrl in providers/openrouterOAuth.ts). The "Open guide" button was its only caller, so on iPhone and iPad the new troubleshooting action would have silently done nothing. Every other docs link in the PR was already an anchor. Rather than special-case the one button, add a `button` variant to DocsLink that renders an anchor wearing Obsidian's button styling, and delete `openDocs` entirely so no future call site can reintroduce the same trap — docs.ts now carries a comment saying why the obvious helper is deliberately absent. The variant matches native buttons exactly: Obsidian sizes them with `height: var(--input-height)` and `4px 12px` padding rather than by content, so a content-sized anchor sat 5px short next to the GitHub buttons in the same row. Verified live at 30px against the real button, with matching background, radius, font size, colour and icon treatment.
Leo310
added a commit
to s2b-dev/site
that referenced
this pull request
Sep 3, 2026
…tour The plugin now links here from a button in its Troubleshooting settings tab (s2b-dev/smart-second-brain#458), so a reader arriving on this page is already looking at that tab. "Start here" then opened by telling them where to find two controls sitting on screen behind the page they had just opened, and the closing section repeated the directions a second time. Reframe the opening around the one thing worth doing before reading further — turn on logging and reproduce — and mention the other controls as things that exist rather than as a place to navigate to. The closing section now assumes that logging is already on and asks for its output in the issue, instead of restating where the buttons live. Also fix the intro's count: it promised "four buckets" and then ran six symptom sections, since MCP and Mobile are not covered by the four named causes. The page is organised by symptom, not by cause, so say that instead of counting.
Same iOS bug Greptile caught on the docs button, in the three call sites that
were already there: the two GitHub issue buttons in Troubleshooting settings and
"Open SkillsMP" in the Add skill modal. Obsidian's iOS WKWebView returns null
from window.open unconditionally, so all three silently did nothing on iPhone
and iPad.
Extract the button-styled anchor from DocsLink into ExternalLinkButton, since
the styling ("an anchor wearing Obsidian's button clothes") is generic while
DocsLink's job is specifically "link to a doc page" — it takes a DocKey and
can't express a GitHub or skillsmp.com URL. DocsLink's button variant now
delegates to it, so there is one implementation of the metrics rather than two.
Left alone: `obsidian://show-plugin` in AgentEditorModal. That goes to the app's
own protocol handler rather than opening a window, so it is unaffected.
Verified live: all four links render at 30px against the real buttons they share
rows with, with matching background, radius, font size and icon treatment, and
carry target="_blank" rel="noopener noreferrer". Screenshot is pixel-identical
to the button version. AGENTS.md gains the rule so this does not come back.
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
1 participant
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.
Why
The docs live in
s2b-dev/siteand the README points at seven of its pages, but the plugin itself linked to the site zero times. Every outbound link insrc/went somewhere else: provider vendor key pages, GitHub issues, andskillsmp.com.manifest.jsonsetsauthorUrl, but I checked Obsidian 1.14.0's bundle — that only linkifies the author name in the community-plugin detail modal, and there is nohelpUrlmanifest field (QuickAdd ships one; the app ignores it). So there is no native docs slot, and a user stuck inside the plugin had exactly one escalation path: open a GitHub issue.What
Links on the six surfaces where someone is either stuck or facing a concept inline copy cannot carry:
/help/troubleshooting//privacy/model//start/providers//agents/skills/,/agents/integrations/,/agents/mcp//agents/skills/In Troubleshooting the guide sits above the GitHub row, which is reworded from "Need more help?" to "Still stuck?" so the docs read as the first stop and GitHub as the escalation. The site's page is organised by symptom, so it should deflect a good share of what would otherwise arrive as issues.
Deliberately skipped: Search/Graph settings (the "how it works" pages are interest-driven reading, not stuck-user reading) and the per-tool config modals (inline descriptions are already at the right altitude).
How
src/utils/docs.ts— one frozen map of every URL. The site's routes have already moved once (itsastro.config.mjsstill carries redirects for the stale links the README had scattered inline), so the next restructure should be a one-file reconciliation rather than a grep. All 15 entries cross-checked against../site/dist/sitemap-0.xml.src/components/ui/DocsLink.svelte— icon variant for setting rows (viaSettingItem's existingnameSuffixsnippet) and inline variant for section descriptions._blanklinks to the system browser on desktop and mobile alike, so these need none of thewindow.openworkarounds the OAuth flow does.One non-obvious change
The onboarding footer's mobile rule had to be rewritten from
.s2b-onboarding-footer > buttonto match through the new wrapper div.display: contentsremoves the wrapper from layout — so Skip does become a flex item of the stacked footer and theorderrules still work — but it does not change the DOM tree a child combinator walks. The old selector would have silently stopped matching and Skip would have lost its quiet styling.Verification
format,lint,check(both tsconfigs) clean; 1644 tests pass.href,target="_blank"andrel="noopener noreferrer"; no console errors.emulateMobile— column order is Start chatting → Explore the graph → Skip → Documentation, Skip transparent, docs link centred.