docs: rebuild the docs site around reader tasks, with a landing page and real-vault screenshots

[chhoumann]

Summary

The docs site at podnotes.obsidian.guide is rebuilt around what a reader is trying to do. Every page follows one standard, every screenshot comes from a script that shows PodNotes in a real, lived-in vault, and the site carries the PodNotes mark.

• Landing page. / is now a splash page. It says what PodNotes is in one line and shows the plugin in a real vault (the episode note and its timestamps on phones). It offers "Get started", a card per job, and three start steps.

• Sidebar by task. The groups are Start here, Listen, Take notes, Your library, Automate, Reference, and Help. There are three new pages:

  • /notes/ (Create episode notes).
  • /settings/ (every setting in the order the settings tab shows them).
  • /playlists/ (queue and playlists, split out of /podcasts/).

• Every page rewritten to docs/STYLE.md, a one-page checklist distilled from Lee Robinson's docs guide, Diátaxis, the Google style guide, Write the Docs, and the Obsidian Help style guide. Each page:

  • Has one job and starts with the common case.
  • Uses verb headings for tasks and numbered steps with one action each.
  • Spells UI labels exactly as PodNotes and Obsidian show them.
  • Describes only the latest release, 2.21.1.

• Screenshots of the real plugin. node docs/scripts/screenshots.mjs builds a vault from a committed seed (docs/screenshots/) and opens it in an isolated, headless Obsidian 1.13.7 at 2x. The vault has:

  • Nine real public feeds and the Minimal theme.
  • Notes created by PodNotes' own commands, with captured timestamps and a Bases view.

  The script writes every shot in light and dark, with phone crops from Obsidian's phone layout where a desktop shot is unreadable at 390 px. It also writes the README demo GIFs and the social preview. Rerun it after the UI redesign.

• The PodNotes mark ("Captured moment", the owner's pick) is the header logo and the favicon:

  • One source SVG, docs/public/brand/podnotes-mark.svg, drawn on a 16 px grid so the 16 px icon stays sharp.
  • node docs/scripts/brand.mjs builds favicon.svg, 16 and 32 px PNGs, and a 180 px apple-touch-icon.png from that file.
  • The social preview shows no brand, so it is unchanged.

• Theme and polish:

  • Inter, the QuickAdd docs palette, and quieter code chips.
  • Tables that stack on phones, and paths that wrap after a slash.
  • Theme-matched <picture> screenshots.
  • OG and Twitter meta, plus a phone theme switch on the landing page.

• Nothing breaks. Every page keeps its URL, and every heading id the site has published (MkDocs and Starlight, 112 ids) still resolves. The build enforces this through legacy-fragments.json. llms.txt, llms-full.txt, and the raw .md pages are unchanged in shape.

Before and after (desktop and phone, light and dark)

Screenshots from the seeded vault

Landing hero	Phone hero (dark)	Phone toolbar

Episode note (dark)	Bases

The mark

Header at 1440 and 390 px, light and dark	Icons at real size and enlarged, on light and dark

Verification

Commands on 0bc5694, Node v22.23.2:

npm run lint            # pass
npm run format:check    # pass
npm run typecheck       # pass
npm run build           # pass
npm run size            # pass: 282,491 raw, 89,833 gzip
npm run test            # pass: 1,589 tests in 96 files
npm run docs:build      # pass: internal links, sidebar completeness, all 112 legacy fragments

npm run test now also runs docs/src/tables.test.mjs. vitest.config.ts includes docs/src/**/*.test.mjs for it.

CodeQL. The three alerts this PR raised are fixed in code:

• docs/src/tables.mjs reads a header cell's text with a tag-aware scan and escapes &, ", <, and >. A test shows that <scr<b>ipt>x leaves no markup in the label.
• docs/scripts/screenshots.mjs sends every value to the page as an argument of one fixed Runtime.callFunctionOn function, never as source text.

Old URLs. The old site published 51 stable URLs: pages, raw Markdown, llms.txt and llms-full.txt, images, the favicon, and sitemaps. Its hashed _astro assets and pagefind index change with every build, so they are left out. All 51 return 200 against the fc65831 build under wrangler pages dev, so _redirects applies as it does on Cloudflare. Each also has the content type its kind expects, and no page serves the 404 page.

Lighthouse 12.8 on python -m http.server, before (current site) and after (three runs on fc65831; the later commits change only text on /QuickAdd/ and /local_files/):

Page	Before (perf, a11y, best practices, SEO, LCP, bytes)	After
Home, mobile	78, 100, 100, 92, 5.9 s, 4,022 KiB	93-94, 100, 100, 100, 3.0-3.2 s, 368 KiB
Home, desktop	98, 100, 100, 92, 1.2 s, 4,022 KiB	100, 100, 100, 100, 0.6-0.7 s, 461 KiB
Template tags, mobile	89, 100, 100, 100, 3.6 s, 575 KiB	94-95, 100, 100, 100, 2.7-2.9 s, 395 KiB
Template tags, desktop	100, 100, 100, 100, 0.7 s, 575 KiB	100, 100, 100, 100, 0.6 s, 395 KiB

Review rounds. There were eleven rounds on the local build. Each round had four reviewers, except round 8, whose visual reviewer stopped on a rate limit. Round 9's visual review covered it.

• A cold reader from each model family (Claude and GPT), with ten to twelve real tasks and only the site to go on.
• A standards and facts reviewer, checking every claim against git show 2.21.1:src/....
• A visual reviewer, checking pages at 1440 and 390 px in light and dark, plus the screenshots.

Coverage was not the same in every round. In rounds 4 and 5 the standards reviewer checked only that round's changes, and before round 6 the visual reviews never covered seven of the pages. Rounds 6 to 11 checked every page in every role, apart from round 8's visual review. The standards and visual roles switched model families from round to round.

Rounds 1 to 4 each found at least one major issue. Round 5 found none, but its coverage was narrow, so an audit of the review trail reopened the review at full coverage. Rounds 6 to 10 each found at least one major issue. All were fixed. Round 11 found none, which ended the review. It covered the mark too.

My fixes for round 11's minor findings were new wording, so three more checks reviewed that diff alone. They found four problems, all fixed:

• A missing Save step in the QuickAdd recipe.
• A download-link sentence that dropped "while the feed still lists it".
• The prompt template name without .md. QuickAdd matches the end of the file's path, so the name needs it. This bug dated from round 10.
• Provider steps that did not match QuickAdd's picker.

The third check found no major.

Findings worth knowing:

• Fact errors at 2.21.1, among them:
  • What Episode list returns to.
  • Imports dropping protected private-feed URLs.
  • The forward-skip end guard.
  • Refresh episodes in Played.
  • The range commands inserting a link even with a plain {{time}} format.
• Wrong Obsidian labels, checked against the 1.13.7 app bundle: the Sync toggle is Installed community plugins, and the Restricted mode button is Exit Restricted mode.
• The QuickAdd recipes are checked against QuickAdd 2.32.1's source, not only its docs.
• Screenshot framing: a stray tooltip, half rows, and a phone shot that cut off the Add buttons.

Runtime. The screenshots are runtime evidence. The script drives PodNotes in Obsidian 1.13.7 the way a user does: it adds feeds in Settings, plays, captures timestamps, and creates notes. They are captured from a build of tag 2.21.1, so they show the released UI.

Release impact

None for the plugin: no src/, settings, storage, API, or URI changes.

The pages describe 2.21.1. These need updating when the merged but unreleased changes ship:

• fix(persistence): merge data.json with changes made on other devices instead of overwriting them #388 and fix(persistence): never let a device that started before sync wipe the synced library #398:
  • sync.md "Use PodNotes on two devices", step 4, and "Changes on two devices".
  • faq.md "Does playback progress sync between devices?".
  • mobile.md, the first item under "Limits on phones".
• docs(sync): explain merged persistence and save recovery #397, the held draft, once it ships: sync.md "Unreadable plugin data".
• fix(feeds): show every podcast and episode, and keep feed lists correct while they load #399:
  • The initials tile for a podcast without artwork, left out here.
  • podcasts.md "When a feed cannot be reached" keeps fix(feeds): show every podcast and episode, and keep feed lists correct while they load #399's published id but describes 2.21.1. A failed fetch falls back to downloads, then episodes loaded this session, then the cached copy only within Cache duration (hours). At release, fix(feeds): show every podcast and episode, and keep feed lists correct while they load #399's text (the saved copy however old it is) replaces the section body.
• fix(player): keep playing while you browse, with one player that owns the media #401: the player text it added to master's old api.md, commands.md, podcasts.md, and timestamps.md. This includes isPlaying, length, and currentTime before the media loads, playback that continues while the view is closed, and the stricter time and endTime URI checks. The merge kept this branch's 2.21.1 wording.
• fix: keep private feed secrets and vault files out of settings and OPML transfers #404:
  • import_export.md: the settings file carries playback progress.
  • import_export.md: the import confirmation names what it replaces.
  • import_export.md: an OPML import restores a private feed's URL.
  • The same OPML route in sync.md "API keys and private feeds on each device".
• perf: cut main.js by 10% with a fuse.js search port and leaner build output #407: nothing user-facing.

Porting #397. #397 can be ported section by section after the release, because every section id it touches still resolves here:

1. Replace the body of "Changes on two devices" with docs(sync): explain merged persistence and save recovery #397's section, and add its "When PodNotes saves" after it.
2. Replace "Unreadable plugin data" with docs(sync): explain merged persistence and save recovery #397's version, including "Restore saving after a notice".
3. Apply its other sync.md edits to "What PodNotes saves", "API keys and private feeds on each device", "Downloads on another device", and "Removed downloads and existing links".
4. In "Use PodNotes on two devices", drop step 4 and its "Step 4 matters" line.
5. Replace the FAQ progress answer with docs(sync): explain merged persistence and save recovery #397's.
6. Rewrite the first item of mobile.md "Limits on phones" to match.

Follow-ups found while capturing, all PodNotes UI and not changed here:

• In Obsidian's phone layout, the search results' Add buttons sit off screen.
• Long queue titles run under the row's menu button.
• The volume and speed sliders show their value twice.
• Playlist rows added from Latest Episodes show no artwork.
• AGENTS.md still says npm install under Common Commands. npm ci keeps the lockfile unchanged.

Note

Rebuild docs site around reader tasks, with landing page and screenshots

• Rewrites all documentation pages as task-oriented guides (getting started, podcasts, notes, timestamps, playlists, sync, transcripts, settings), organized in a seven-group sidebar in site.mjs.
• Adds a custom Starlight hero landing page in index.md and Hero.astro, with light/dark and phone screenshot variants.
• Adds an automated screenshot workflow: a seeded capture vault and an Obsidian-driven capture script in screenshots.mjs generate the real-vault screenshots used across the site.
• Applies new PodNotes theming (self-hosted Inter font, accent palette, stacked responsive tables) via custom.css and astro.config.mjs; documents the standard in STYLE.md.
• Behavioral Change: sidebarSections in markdown.ts no longer creates a synthetic ungrouped Docs section and now omits external sidebar links; legacy heading IDs are preserved via legacy-fragments.json.

^{Macroscope summarized 0bc5694.}

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $12.70, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

File	Diff Size	Estimate
docs/scripts/screenshots.mjs	33.83KB	$1.69
docs/src/content/docs/templates.md	22.19KB	$1.11
docs/src/content/docs/sync.md	14.55KB	$0.73

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}

[cloudflare-workers-and-pages]

Deploying podnotes with    Cloudflare Pages

Latest commit:	0bc5694
Status:	✅  Deploy successful!
Preview URL:	https://9f6ea439.podnotes.pages.dev
Branch Preview URL:	https://docs-overhaul.podnotes.pages.dev

View logs