Repository navigation
docs: rewrite the README for new users and add a contributing guide - #414
Merged
Merged
Conversation
docs/STYLE.md is the checklist every docs page follows. docs/scripts/screenshots.mjs builds a lived-in vault from docs/screenshots, drives PodNotes in a private Obsidian capture instance, and writes light and dark screenshots to docs/public/screenshots.
…laylists into their own page
…nd calmer headings Screenshots whose text is unreadable on a phone get a -phone crop from Obsidian's phone layout, served through <picture>. The hero folds its properties away so the timestamps sit mid-window, the Bases shot fits its columns, and the mobile player is cropped to the drawer. Tables span the column on desktop, settings tables share fixed columns, paths in table cells break on phones, and short code chips stay on one line. Group headings above a question get a rule, anchor icons hide on touch screens, external sidebar links show an arrow, and the dark phone menu button no longer glares.
…ero, and cleaner crops The episode-note screenshot now sits under the template that produced it. Phones see the episode note with its timestamp links in the landing hero, and the desktop hero sits higher so its timestamps show above the fold. Note, Bases, player, and toolbar crops lose their stray edges, caret, and tooltip. The phone search crop is gone: in Obsidian's phone layout, PodNotes places each result's Add button off screen, so phones get the desktop shot. Code in settings tables wraps instead of overlapping the next column.
The README leads with what PodNotes does, shows the capture demo in light and dark, and links into the docs site instead of repeating it. CONTRIBUTING.md covers setup, the checks, testing in Obsidian, docs changes, and pull requests, and points to AGENTS.md for the details.
…s, and clearer steps Phone captures park the pointer where no tooltip can open and clear the floating header's shadow. The search shot is the settings card alone, with an even margin, and the README demo starts at the note's artwork. Paths in tables break after a slash, the settings Default column is wider, and phone table cells align to the top. Adding by RSS URL is its own steps, the top buttons are named by position, and the FAQ's plain-text fix matches the timestamps page.
# Conflicts: # docs/src/content/docs/podcasts.md
The README's images use absolute URLs, so the dark demo also shows on community.obsidian.md, and phones get the note screenshot instead of the demo. The install step turns off Restricted mode. CONTRIBUTING starts with a build that finishes, tries builds in the isolated Obsidian on macOS and Linux, and lists the same checks as CI.
…n Sync toggle correctly Obsidian labels the second Vault configuration sync toggle Installed community plugins, and it carries each plugin's settings, which hold the PodNotes library. The notes page labels its template as an example that replaces the default, Getting started points to it, the phone toolbar step names the clock button, and the player times are explained. Inline paths and URLs break after a slash. The hero's theme twins load lazily, so a visit downloads only the one it shows. Screenshots are now captured from the 2.21.1 release bundle. The phone note shot has room below its callout, and the demo window shows whole queue rows.
…ble labels The screenshot script ran every step in Obsidian as code built with JSON.stringify'd values. It now sends fixed code through Runtime.callFunctionOn and passes the values as the call's argument, including waitFor, click, fill, and crop rects, so no value is written into code. Stacked table labels take the header's text with a tag-aware scan instead of one regex pass, and escape <, >, &, and ". A test covers a nested tag.
CONTRIBUTING says to set up Obsidian's command line client, which the test tools need, and when the isolated instance stops. The README states the Obsidian version, says when Deepgram transcribes, and gives the command palette in its third step.
# Conflicts: # docs/src/content/docs/api.md # docs/src/content/docs/commands.md # docs/src/content/docs/podcasts.md # docs/src/content/docs/timestamps.md
At 2.21.1 PodNotes sends audio to Deepgram only when speaker labels are on with Deepgram as the provider. The landing page and the transcription page implied a Deepgram key alone could transcribe.
A full-site standards pass found three claims that the earlier diff-only rounds could not see. The transcription steps sent OpenAI users to a hidden Deepgram field. Sync and import described a data-format check as a plugin-version check. All three are fixed, and Getting started now creates the episode note before capturing into it. Restricted mode's control is named as Obsidian shows it, Exit Restricted mode. The API headings carry the method name, with the signature in a code block below, so they fit a phone. Code blocks wrap, headings balance their lines, and command IDs stay whole on desktop. STYLE records the tutorial and FAQ exceptions to the one-owner rule.
CONTRIBUTING names the CLI dialog's Register button, installs with npm ci, points to the isolated-instance section of AGENTS.md, and says where a breaking-change footer goes. The README names Exit Restricted mode and says Deepgram transcribes when you choose it for speaker labels.
The transcription page opened by saying it needs an OpenAI account, which contradicted its own table, where Deepgram needs no OpenAI key. The opening now states which provider runs when, and the landing card and description stay neutral. Refresh episodes is scoped to the lists where it fetches, and the import warning names Import settings. Section headings balance their lines, menu paths stay on one line, the QuickAdd offset call sits in its own code block, and the phone toolbar shot is framed closer under the note.
The template tag rules claimed to cover every template, but Speaker label format only replaces {{speaker}}. The rules now exclude it, and the page says what it does. The QuickAdd page gives the transcript-prompt macro its own steps, instead of linking in a circle with the API page, and says a timestamp with a comment needs no macro.
The queue sentences say they hold only with the automatic queue on, Refresh episodes says what it does in a playlist, and a flat notes path warns that same-titled episodes share a note. Landing card titles take the link color.
Refresh episodes fetches in Played too, not only in Latest Episodes and a podcast's list. The episode menu table now matches Downloads and local files: Remove from Local Files keeps your own file. The QuickAdd transcript recipe carries its script and its AI Assistant prerequisite, and the API page points to it. The private-feed notice, the FAQ's private-feed triggers, and the speaker label format's location and Deepgram labels match 2.21.1.
The range commands insert a link only with the default capture format. With {{time}}, they insert a plain-text range, so the Commands and Capture timestamps pages now say so. The QuickAdd transcript recipe runs from setting up the AI Assistant to a summary written into your note, using the labels in QuickAdd's own docs.
Six instructions written as prose are numbered steps now: playing an episode, the automatic queue, downloading the playing episode, the Bases table, capturing a range, and the speaker label format.
The queue and playlists page shows how to remove an episode from a list, and the podcasts page promises only what it covers. Links to your own files need their Local Files entry, and the FAQ and Local Files say how to restore them. The list controls on the podcasts page are bullets, and the transcript prompt script builds its prompt from quoted lines.
The owner chose the Captured moment mark: a waveform with one moment pinned. docs/public/brand/podnotes-mark.svg is the single source. It is drawn on a 16 px grid so the smallest favicon stays sharp, and docs/scripts/brand.mjs builds the SVG favicon, the 16 and 32 px favicons, and the Apple touch icon from it. The header shows the mark beside the name.
The steps that select a choice by name now show it as a UI label, like the rest of the site.
The QuickAdd AI recipe names each control, from Add AI Assistant command to the capture's write position, and the page says to install QuickAdd and to create scripts in a text editor. A range captured with {{time}} is plain text. The player's Queue list has no list controls, the queue move items say when they appear, and deleting a playlist keeps its episodes. Links to your own file stop working until you play the file with PodNotes again.
QuickAdd matches the prompt template by the end of its path, so the field takes the file name with .md, and the AI Assistant's settings need Save. The recipe splits into setting up the AI Assistant, building the prompt, and writing the summary, one action per step. Links to a download stream from the feed only while the feed lists the episode.
QuickAdd lists OpenAI and Gemini under Providers from the start, so the setup selects one and sets its API key. Other providers connect from their card with a key. The AI Assistant command sets a model, so the run does not stop to ask for one.
Deploying podnotes with
|
| Latest commit: |
6fe759d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c07efa92.podnotes.pages.dev |
| Branch Preview URL: | https://docs-readme.podnotes.pages.dev |
# Conflicts: # docs/src/content/docs/podcasts.md
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.
Summary
#403 merged as 527878d, adding the mark, the screenshots this README shows, and the
/notes/page it links. This branch merges master, so its diff is README.md and CONTRIBUTING.md.The README now introduces PodNotes to someone who finds it on GitHub or in Obsidian's plugin directory. Developer material moves to a new
CONTRIBUTING.md.docs/public/brand/podnotes-mark.svg, added in docs: rebuild the docs site around reader tasks, with a landing page and real-vault screenshots #403).<img src>but not a relative<source srcset>. Relative URLs would show the dark demo as a broken image there.https://obsidian.md/plugins?id=podnotes. GitHub stripsobsidian://links from READMEs.BREAKING CHANGE:footer.AGENTS.mdfor the details.As GitHub renders it
These renders were captured before #403 merged, so they served the README's images from this branch. The images now load from master.
The top of each, larger:
Verification
CONTRIBUTING.mdwas checked againstpackage.json,.nvmrc,.npmrc, the e2e runner, the PR template, and the title workflow.npm run start:e2e-obsidianfails after 31 s, three times out of three.evalblock inzsh -fandbash --norc, and sawnpm run start:e2e-obsidianstart in 1 s with the client installed. Minors applied: the dialog's Register button,npm ciinstead ofnpm install, theAGENTS.mdisolated-instance link, where theBREAKING CHANGE:footer goes, and the Deepgram provider condition.Release impact
None. The README and CONTRIBUTING describe 2.21.1 and change no code.