feat(notes): ship a Bases-friendly default episode note template (#160) (#201)

* feat(notes): ship a Bases-friendly default episode note template (#160)

The episode note path/template both defaulted to "" (empty), which left the
"Create episode note" command disabled on a fresh install and gave new users
no structured metadata. Ship sensible defaults:

- note.path: PodNotes/{{podcast}}/{{title}}.md (matches the download convention)
- note.template: Bases-friendly frontmatter (type/podcast-link/url/date/tags +
  user-fillable status/rating/favorite), with the raw title as the body H1 so
  YAML rules never apply to it. {{podcastlink}} ties each episode to its #163
  feed note for Bases/Dataview rollups.

Make the frontmatter bulletproof: NoteTemplateEngine now sanitizes the URL tags
({{url}}/{{stream}}/{{artwork}}/{{episodeurl}}/{{episodeartwork}}/{{feedurl}}/
{{feedartwork}}) by stripping " and \\ (lossless for valid URLs), mirroring
FeedNoteTemplateEngine, so a quoted scalar like url: "{{url}}" stays valid.

Migrate existing users without clobbering customizations: migrateNotePath /
migrateNoteTemplate upgrade ONLY the exact legacy empty value (or absent), so
any non-empty path/template the user configured is preserved. Mirrors the #183
migrateDownloadPath precedent and is wired into loadSettings.

Update the e2e provisioning seed to match (keeps the seed/DEFAULT_SETTINGS drift
test green and seeds the new default for verification), refresh the settings
placeholder, and document the default + an example .base view in templates.md.

Verified in the isolated worktree Obsidian vault: notes created via the real
create-podcast-note command (incl. a hostile title/URL and a no-date episode)
parse into clean frontmatter via Obsidian's properties parser.

* fix(notes): harden URL-tag sanitization and correct Bases docs (#160 review)

Address ultracode review findings on the #160 default template:

- NoteTemplateEngine: guard {{url}}/{{stream}}/{{episodeurl}} with `?? ""` before
  sanitizeUrlForTemplate, matching the other URL tags. A corrupted/hand-edited
  data.json could surface a null/undefined on these typed-string fields, where
  the unguarded `.replace` would throw and abort note creation. Add a regression
  test covering a corrupted episode.
- docs/templates.md: the default puts {{artwork}} in the body as a Markdown image,
  not a quoted frontmatter scalar; correct the YAML-safety bullet to say so.
- docs/templates.md: quote the example .base filter condition
  ('type == "podcastEpisode"') to match Obsidian's canonical Bases syntax.

* fix(notes): tighten note migration and Bases docs (#160 adversarial review)

Address findings from the adversarial review of the #160 default template:

- Migration: only upgrade the legacy empty note when the WHOLE note is the old
  default (path AND template both empty/absent). Replace the per-field
  migrateNotePath/migrateNoteTemplate with migrateNoteSettings so a user who
  configured one field and deliberately left the other empty (e.g. a custom path
  with an empty template to keep "Create episode note" disabled) is never
  silently re-enabled. Coalesce null fields so a corrupted data.json can't reach
  the path/template engines. Update tests to cover the preserve-partial case.
- docs/templates.md: the example .base used a `sort:` view key, which is not part
  of the documented Obsidian Bases schema (sorting is view UI state; only
  `order` + `groupBy` are documented). Switch to `groupBy` (by listening status)
  and `note.`-prefixed properties, matching the canonical syntax.
- Qualify the "always valid YAML" claim (docs + constants comment): the guarantee
  holds for the default and any ordinary feed-note path; a feed-note path with a
  literal quote/backslash in a folder segment would flow into {{podcastlink}}.

* fix(notes): render URL tags verbatim, don't mutate them globally (#160 review)

Codex review (P2): globally stripping "/\ from NoteTemplateEngine's URL tags
corrupts {{url}} for local-file episodes, where episode.url is a wikilink from
generateMarkdownLink (e.g. a file named Talk "A".mp3 would link to Talk A.mp3),
and changes existing custom templates that use {{url}} outside YAML.

Revert the URL-tag sanitization added earlier in this branch back to master's
verbatim behavior. The default frontmatter stays valid YAML for the common case
without mutating tag values: feed episode URLs are well-formed (no quotes), the
{{podcastlink}} name is already sanitized, and ordinary local-file links contain
no quotes. A URL or file name with a literal quote is the one case that would
need adjusting, which is documented. sanitizeUrlForTemplate stays in use by
FeedNoteTemplateEngine, where {{url}} is always a real website URL.

Add a test guarding that {{url}}/{{episodeurl}} pass through verbatim (local-file
wikilinks preserved), and update the docs/comment claims accordingly.

* fix(notes): keep {{url}} out of the default frontmatter scalar (#160 review)

Codex review (P2): after rendering URL tags verbatim, a local-file episode whose
name contains a double quote (e.g. Talk "A".mp3, playable on macOS/Linux) makes
{{url}} a wikilink with a quote, so url: "{{url}}" renders
url: "[[Talk "A".mp3]]" and the whole frontmatter fails to parse, hiding every
property from Bases.

Move {{url}} (and it was already true for {{artwork}}) into the note body, where
YAML rules don't apply, so the verbatim tag value can never break the
frontmatter. The frontmatter now contains only values that can't carry a
YAML-hostile character (type, the sanitized {{podcastlink}}, an ISO/empty date,
tags, and the user-fillable status/rating/favorite). Feed-only users can add
url: "{{url}}" back; documented. Update the example, the e2e seed, and the test
(now exercises a quote-bearing local-file url to prove the frontmatter stays
parseable).

Author: chhoumann

docs/docs/templates.md

@@ -3,6 +3,8 @@ PodNotes can create notes from templates. These templates can contain certain sy
 To use templates, you can use the `Create episode note` Obsidian command (previously named `Create podcast note`).
 This requires you to have defined a template for both the file path and note text.
 
+PodNotes ships a sensible default for both, so the command works out of the box on a fresh install. The default note template uses structured frontmatter properties that [Obsidian Bases](https://help.obsidian.md/bases) can sort, filter, and group on (see [Using the default template with Bases](#using-the-default-template-with-bases) below). You can customize either template under PodNotes settings at any time, and your customizations are always preserved across updates.
+
 PodNotes can also create a note for a whole podcast (the feed). See [Podcast feed notes](#podcast-feed-notes) below.
 
 ## File path
@@ -28,7 +30,7 @@ This template will be used to create the note text. You can use the following sy
 	-  You can use `{{content:> }}` to prepend each new line with a `>` (to put the entire content in a blockquote).
 
 - `{{podcast}}`: The name of the podcast.
-- `{{url}}`: The URL of the podcast episode.
+- `{{url}}`: The URL of the podcast episode. For a local-file episode this is a link to the file rather than a web URL. Tag values are inserted verbatim, so when you place one in a quoted YAML property (e.g. `url: "{{url}}"`) it stays valid for well-formed feed URLs and ordinary file names (a URL or file name containing a literal `"` would need escaping).
 - `{{stream}}`: The direct URL of the episode's audio file — the RSS `<enclosure>` URL for podcast feeds, or the underlying audio source for Pocket Casts and local-file episodes. Handy for embedding the raw audio or linking to the source. An empty string is used in the rare case no audio URL is available. Available in episode note templates only.
 - `{{date}}`: The publish date of the podcast episode.
 	- You can use `{{date:format}}` to specify a custom [Moment.js](https://momentjs.com) format. E.g. `{{date:YYYY-MM-DD}}`.
@@ -51,22 +53,62 @@ In an episode note, `{{url}}` and `{{artwork}}` always describe the **episode**.
 - `{{feedartwork}}`: The podcast's (feed) artwork. Falls back to the episode artwork if the feed isn't saved.
 - `{{podcastlink}}`: A ready-made wikilink to the podcast's [feed note](#podcast-feed-notes). It points at the same file the feed note is created at, so episodes and the feed note link up automatically. When the feed-note path has a folder it is path-qualified (e.g. `[[PodNotes/Podcasts/My Show|My Show]]`) so it can't resolve to an unrelated note that shares the basename; otherwise it's a plain `[[My Show]]`. (Avoid putting a `{{date}}` in the feed-note path, since the episode side can't reproduce the feed note's creation date.)
 
-A Bases-friendly episode template that links back to the feed note:
+### Using the default template with Bases
+PodNotes ships this default episode note template, which links each episode back to its feed note and exposes structured frontmatter properties for [Obsidian Bases](https://help.obsidian.md/bases):
 
 ```
 ---
 type: podcastEpisode
 podcast: "{{podcastlink}}"
-title: "{{title}}"
-image: "{{artwork}}"
-url: "{{url}}"
 date: {{date:YYYY-MM-DD}}
 tags:
   - podcastEpisode
+status:
+rating:
+favorite: false
 ---
+# {{title}}
+
+![]({{artwork}})
+
+[Resume in PodNotes]({{episodelink}})
+
+{{url}}
+
 {{description}}
 ```
 
+The frontmatter is built so it stays **valid YAML** for every episode, because only values that can never contain a YAML-hostile character go into it:
+
+- The full episode title goes in the body as the `# {{title}}` heading, where YAML rules don't apply (a raw title can contain `"` or `:`, which would break a frontmatter scalar).
+- `{{podcastlink}}` is quoted so its leading `[[` isn't read as a YAML flow sequence, and the linked name is sanitized. (If you customize *Feed note file path* to a folder containing a literal `"` or `\`, that character flows into the link verbatim — keep the feed-note path to ordinary path characters.)
+- `{{url}}` and `{{artwork}}` are kept in the **body** (a bare link and a Markdown image), not in the frontmatter. Tag values are inserted verbatim, and for a local-file episode `{{url}}` is a vault link whose name can contain a `"`; keeping it out of a quoted scalar means an awkward URL or file name can never break the note's properties. If your episodes all come from feeds (so `{{url}}` is always a well-formed web URL), you can add `url: "{{url}}"` back to the frontmatter.
+- `date:` is a bare `YYYY-MM-DD` (or empty/null when the feed has no publish date).
+- `status`, `rating`, and `favorite` are left for you to fill in — they give Bases columns to sort and filter on (e.g. mark an episode `favorite: true`, or set `status` to `to-listen`/`listening`/`listened`).
+
+A starter Bases view (save as e.g. `Podcast Episodes.base`) that lists every episode note, grouped by listening status, with a column for each property:
+
+```yaml
+filters:
+  and:
+    - 'type == "podcastEpisode"'
+views:
+  - type: table
+    name: Episodes
+    order:
+      - file.name
+      - note.podcast
+      - note.date
+      - note.status
+      - note.rating
+      - note.favorite
+    groupBy:
+      property: note.status
+      direction: ASC
+```
+
+Open the base in Obsidian to sort, filter, or add views from the view options. Because `note.podcast` resolves to the linked [feed note](#podcast-feed-notes), you can also group by show or pivot from a feed note to all of its episodes.
+
 ## Podcast feed notes
 A *feed note* is a single parent note for an entire podcast (the feed), which episode notes can link to (great for [Obsidian Bases](https://help.obsidian.md/bases) / Dataview rollups).
 

scripts/provision-obsidian-e2e-vault.mjs

@@ -52,8 +52,23 @@ export const DEFAULT_PODNOTES_DATA = {
 		offset: 0,
 	},
 	note: {
-		path: "",
-		template: "",
+		path: "PodNotes/{{podcast}}/{{title}}.md",
+		template:
+			"---\n" +
+			"type: podcastEpisode\n" +
+			'podcast: "{{podcastlink}}"\n' +
+			"date: {{date:YYYY-MM-DD}}\n" +
+			"tags:\n" +
+			"  - podcastEpisode\n" +
+			"status:\n" +
+			"rating:\n" +
+			"favorite: false\n" +
+			"---\n" +
+			"# {{title}}\n\n" +
+			"![]({{artwork}})\n\n" +
+			"[Resume in PodNotes]({{episodelink}})\n\n" +
+			"{{url}}\n\n" +
+			"{{description}}\n",
 	},
 	feedNote: {
 		path: "PodNotes/Podcasts/{{podcast}}.md",

src/TemplateEngine.test.ts

@@ -11,6 +11,7 @@ import {
 import type { Episode } from "./types/Episode";
 import type { PodcastFeed } from "./types/PodcastFeed";
 import { downloadedEpisodes, plugin } from "./store";
+import { DEFAULT_SETTINGS } from "./constants";
 
 // The illegal-character sanitizer is private; exercise it through
 // DownloadPathTemplateEngine, which applies it to {{title}} and {{podcast}}.
@@ -144,6 +145,108 @@ describe("NoteTemplateEngine feed-scoped tags (#163)", () => {
 	});
 });
 
+describe("NoteTemplateEngine renders URL tags verbatim (#160 review)", () => {
+	beforeEach(() => {
+		plugin.set({
+			settings: { feedNote: { path: "" }, savedFeeds: {} },
+		} as never);
+	});
+
+	it("does not mutate {{url}}/{{episodeurl}} — local-file wikilinks pass through", () => {
+		// For local-file episodes episode.url is a wikilink, not a URL
+		// (getContextMenuHandler stores generateMarkdownLink). The engine must not
+		// strip characters from it, or the link would point at a different file.
+		const localFile = {
+			...demoEpisode,
+			url: '[[Talk "A".mp3]]',
+		} as Episode;
+		expect(NoteTemplateEngine("{{url}}", localFile)).toBe('[[Talk "A".mp3]]');
+		expect(NoteTemplateEngine("{{episodeurl}}", localFile)).toBe(
+			'[[Talk "A".mp3]]',
+		);
+	});
+
+	it("renders a normal episode URL and artwork verbatim", () => {
+		expect(NoteTemplateEngine("{{url}}|{{artwork}}", demoEpisode)).toBe(
+			"https://example.com/ep1|https://example.com/ep1.png",
+		);
+	});
+});
+
+describe("default note template renders valid frontmatter (#160)", () => {
+	beforeEach(() => {
+		plugin.set({
+			settings: {
+				feedNote: { path: "PodNotes/Podcasts/{{podcast}}.md" },
+				savedFeeds: {},
+			},
+		} as never);
+		downloadedEpisodes.set({});
+	});
+
+	function frontmatterOf(rendered: string): string {
+		const match = rendered.match(/^---\n([\s\S]*?)\n---\n/);
+		expect(match).not.toBeNull();
+		return (match as RegExpMatchArray)[1];
+	}
+
+	it("keeps frontmatter valid even when title/url carry YAML-hostile characters", () => {
+		// A local-file episode whose name contains a quote is the worst case: the
+		// title carries quotes/colons and {{url}} is a wikilink containing a quote.
+		// Both must stay in the BODY (never a quoted frontmatter scalar) so the
+		// frontmatter always parses. See issue #160 review.
+		const episode: Episode = {
+			...demoEpisode,
+			title: 'Why "AI": a deep dive: part 2',
+			url: '[[Audio/Talk "A".mp3]]',
+			podcastName: "My Show",
+		};
+		const rendered = NoteTemplateEngine(
+			DEFAULT_SETTINGS.note.template,
+			episode,
+		);
+		const frontmatter = frontmatterOf(rendered);
+		const line = (key: string) =>
+			frontmatter.split("\n").find((l) => l.startsWith(`${key}:`));
+
+		// The podcast link is quoted so its leading [[ isn't read as a flow sequence.
+		expect(line("podcast")).toBe(
+			'podcast: "[[PodNotes/Podcasts/My Show|My Show]]"',
+		);
+		// The url is NOT in the frontmatter (it could carry a quote for local files).
+		expect(line("url")).toBeUndefined();
+		// Every frontmatter line has balanced double-quotes.
+		for (const l of frontmatter.split("\n")) {
+			expect((l.match(/"/g) ?? []).length % 2).toBe(0);
+		}
+		// The raw title (quotes/colons) and the raw url (a quote-bearing wikilink)
+		// live only in the body, where YAML rules don't apply.
+		const body = rendered.slice(rendered.indexOf("\n---\n") + 5);
+		expect(body).toContain('# Why "AI": a deep dive: part 2');
+		expect(body).toContain('[[Audio/Talk "A".mp3]]');
+		expect(frontmatter).not.toContain("deep dive");
+		expect(frontmatter).not.toContain("Talk");
+	});
+
+	it("renders an ISO date when present and an empty (null) date otherwise", () => {
+		const withDate = NoteTemplateEngine(
+			DEFAULT_SETTINGS.note.template,
+			demoEpisode,
+		);
+		expect(
+			withDate.split("\n").find((l) => l.startsWith("date:")),
+		).toBe("date: 2024-01-01");
+
+		const noDate = NoteTemplateEngine(DEFAULT_SETTINGS.note.template, {
+			...demoEpisode,
+			episodeDate: undefined,
+		});
+		const dateLine = noDate.split("\n").find((l) => l.startsWith("date:"));
+		// Empty publish date renders as a null property, never a broken value.
+		expect(dateLine?.replace(/\s+$/, "")).toBe("date:");
+	});
+});
+
 describe("FeedNoteTemplateEngine (#163)", () => {
 	const feed: PodcastFeed = {
 		title: "My Show: A Podcast",

src/constants.ts

@@ -82,8 +82,38 @@ export const DEFAULT_SETTINGS: IPodNotesSettings = {
 	},
 
 	note: {
-		path: "",
-		template: "",
+		// Group episode notes under a per-podcast folder, matching the download
+		// path convention (PodNotes/{{podcast}}/{{title}}). See issue #160.
+		path: "PodNotes/{{podcast}}/{{title}}.md",
+		// Bases-friendly frontmatter so new installs get queryable episode metadata
+		// out of the box (issue #160). Every value here is guaranteed valid YAML
+		// because none of them can contain a YAML-hostile character: {{podcastlink}}
+		// is a wikilink whose name is sanitized (no quotes) and is quoted so its
+		// leading "[[" can't be read as a flow sequence, and {{date:YYYY-MM-DD}} is
+		// either an ISO date or empty (null). status/rating/favorite are left for the
+		// user to fill and give Bases columns to sort and filter on. The raw
+		// {{title}} (which may contain quotes/colons) and {{url}} (a feed URL, or for
+		// a local file a vault link whose name may contain a quote) live in the BODY,
+		// where YAML rules don't apply — keeping the verbatim, unescaped tag values
+		// out of quoted frontmatter scalars so the frontmatter never fails to parse
+		// (issue #160 review). {{podcastlink}} ties each episode to its feed note
+		// (#163). See issue #160.
+		template:
+			"---\n" +
+			"type: podcastEpisode\n" +
+			'podcast: "{{podcastlink}}"\n' +
+			"date: {{date:YYYY-MM-DD}}\n" +
+			"tags:\n" +
+			"  - podcastEpisode\n" +
+			"status:\n" +
+			"rating:\n" +
+			"favorite: false\n" +
+			"---\n" +
+			"# {{title}}\n\n" +
+			"![]({{artwork}})\n\n" +
+			"[Resume in PodNotes]({{episodelink}})\n\n" +
+			"{{url}}\n\n" +
+			"{{description}}\n",
 	},
 
 	feedNote: {

src/main.ts

@@ -16,7 +16,10 @@ import { Plugin, type WorkspaceLeaf } from "obsidian";
 import { API } from "src/API/API";
 import type { IAPI } from "src/API/IAPI";
 import { DEFAULT_SETTINGS, VIEW_TYPE } from "src/constants";
-import { migrateDownloadPath } from "src/settingsMigrations";
+import {
+	migrateDownloadPath,
+	migrateNoteSettings,
+} from "src/settingsMigrations";
 import { PodNotesSettingsTab } from "src/ui/settings/PodNotesSettingsTab";
 import { MainView } from "src/ui/PodcastView";
 import { QueueReorderModal } from "src/ui/QueueReorderModal";
@@ -495,6 +498,10 @@ export default class PodNotes extends Plugin implements IPodNotes {
 		this.settings.episodeListLimit = sanitizeEpisodeListLimit(
 			this.settings.episodeListLimit,
 		);
+		// Upgrade the legacy empty episode-note default to the Bases-friendly
+		// default, preserving any path/template the user configured (#160). Returns
+		// a fresh object, so DEFAULT_SETTINGS.note is never mutated.
+		this.settings.note = migrateNoteSettings(loadedData?.note);
 	}
 
 	async saveSettings() {

src/settingsMigrations.test.ts

@@ -3,6 +3,7 @@ import { DEFAULT_SETTINGS } from "./constants";
 import {
 	LEGACY_EMPTY_DOWNLOAD_PATH,
 	migrateDownloadPath,
+	migrateNoteSettings,
 } from "./settingsMigrations";
 
 describe("download path default (#183)", () => {
@@ -47,3 +48,78 @@ describe("migrateDownloadPath (#183)", () => {
 		expect(migrateDownloadPath(once)).toBe(DEFAULT_SETTINGS.download.path);
 	});
 });
+
+describe("episode note defaults (#160)", () => {
+	it("ships a non-empty path with per-episode and per-podcast tokens", () => {
+		expect(DEFAULT_SETTINGS.note.path).not.toBe("");
+		expect(DEFAULT_SETTINGS.note.path).toMatch(/\{\{\s*title\b/i);
+		expect(DEFAULT_SETTINGS.note.path).toMatch(/\{\{\s*podcast\b/i);
+	});
+
+	it("ships a non-empty Bases-friendly template with frontmatter", () => {
+		const template = DEFAULT_SETTINGS.note.template;
+		expect(template).not.toBe("");
+		// Opens with a YAML frontmatter block...
+		expect(template.startsWith("---\n")).toBe(true);
+		// ...that closes before the body H1.
+		expect(template.indexOf("\n---\n")).toBeLessThan(
+			template.indexOf("# {{title}}"),
+		);
+		// Carries the structured properties Bases sorts/filters on.
+		expect(template).toContain("type: podcastEpisode");
+		expect(template).toMatch(/^tags:/m);
+	});
+});
+
+describe("migrateNoteSettings (#160)", () => {
+	const DEFAULT_NOTE = {
+		path: DEFAULT_SETTINGS.note.path,
+		template: DEFAULT_SETTINGS.note.template,
+	};
+
+	it("upgrades the legacy empty note (both fields empty) to the default", () => {
+		expect(migrateNoteSettings({ path: "", template: "" })).toEqual(
+			DEFAULT_NOTE,
+		);
+	});
+
+	it("treats an absent note (undefined/null/empty object) as the legacy default", () => {
+		expect(migrateNoteSettings(undefined)).toEqual(DEFAULT_NOTE);
+		expect(migrateNoteSettings(null)).toEqual(DEFAULT_NOTE);
+		expect(migrateNoteSettings({})).toEqual(DEFAULT_NOTE);
+	});
+
+	it("coalesces null/undefined fields and still upgrades a fully-absent note", () => {
+		// A corrupted/hand-edited data.json could carry nulls; they must not reach
+		// the path/template engines (null.replace would throw) and a wholly-empty
+		// note still upgrades.
+		expect(migrateNoteSettings({ path: null, template: null })).toEqual(
+			DEFAULT_NOTE,
+		);
+	});
+
+	it("preserves a fully-configured note verbatim", () => {
+		const custom = {
+			path: "inputs/podcasts/{{podcast}} - {{title}}.md",
+			template: "## {{title}}\n{{description}}",
+		};
+		expect(migrateNoteSettings(custom)).toEqual(custom);
+	});
+
+	it("never overwrites a deliberately-empty field once the user configured the other", () => {
+		// Custom path + empty template = note creation deliberately disabled; the
+		// empty template must NOT be filled with the new default (would re-enable
+		// the command). Symmetric for a custom template + empty path.
+		expect(
+			migrateNoteSettings({ path: "Custom/{{title}}.md", template: "" }),
+		).toEqual({ path: "Custom/{{title}}.md", template: "" });
+		expect(
+			migrateNoteSettings({ path: "", template: "## {{title}}" }),
+		).toEqual({ path: "", template: "## {{title}}" });
+	});
+
+	it("is idempotent on the current default", () => {
+		const once = migrateNoteSettings(DEFAULT_NOTE);
+		expect(migrateNoteSettings(once)).toEqual(DEFAULT_NOTE);
+	});
+});