filestarter

A better Obsidian starter plugin (back when starters mattered)

Filestarter — first known as obsidian-plugin-starter — was built because Obsidian's own sample plugin is so simple it's useless: a single ribbon icon and a hello-world modal. We wanted a starter that actually showed off the API surface, with current dependencies and modal/command patterns wired in. Logged retrospectively from 2026, because the world has changed since.

All ship notes

Why Care?

Every Obsidian plugin developer forks the same official sample plugin to start. It is, charitably, a hello world: one ribbon icon, one modal that says hi, a settings tab with one toggle. It does not show you how to do any of the things a real plugin needs to do — work with the active editor, walk a vault, render a serious modal, register commands with checkbacks, handle the file system carefully.

In September 2025 we wrote our own starter to fix that. This is the changelog entry for the day it shipped — and the moment to acknowledge that, less than a year later, the role of a starter plugin has changed.

What's New?

(Historical. Single foundational commit.)

  • feature(table-of-contents, callout-handling) — the only commit before the May 2026 content-farm relocation. It contains:

    • Updated dependency stack — obsidian typings current, esbuild config that builds cleanly, manifest fields aligned with the latest community-plugin requirements.

    • A working table-of-contents generator — given a markdown document, walk the headings, produce a TOC, render it back into the note. Demonstrates editor-state reading and writing.

    • Callout handling for Obsidian's > [!note]-style syntax, lifted into structured nodes downstream code can act on. Demonstrates serious markdown parsing.

    • The unified wide-modal pattern — header / labeled sections / footer with primary CTA, Cmd/Ctrl+Enter submit. Demonstrates a modal that's actually useful.

    • Command registrations that show the various flavors (editor commands, file commands, vault-wide commands, with checkback variants).

The premise: by the time you fork this, you've already seen working examples of the patterns you'll want — not from third-party blog posts and Stack Overflow archaeology, but from a single repo we maintain.

The arc

By September 2025 we had a half-dozen plugins in flight (cite-wide, image-gin, perplexed, plunk-it, lmstud-yo, the early Google Docs experiment) and were tired of the same opening hour every time: copy a manifest, set up esbuild, wire the basic modal pattern, write a TOC helper because nothing in markdown world gives you one for free, register commands the right way.

The fix was the obvious one: a starter we maintained ourselves, opinionated toward what we'd repeatedly needed.

September 30, 2025: one focused commit, everything in place. The starter has been mostly dormant since — which is the right outcome for a starter. You don't want a starter that grows and breaks the people who forked it months ago. You want one that's solid enough to fork without revision.

What changed in the year since

By May 2026 — when this retrospective is being written — the case for a starter plugin has weakened considerably. AI-assisted coding scaffolds plugins competently from a one-paragraph prompt. The friction this starter was designed to remove (figuring out the API surface, finding working examples, getting the build clean) is now removed by Claude or Cursor in the time it takes to write the prompt.

So no one really needs a starter plugin anymore.

But people still need a filestarter. Hence the rename, in May 2026, from obsidian-plugin-starter to filestarter. The repo's role is shifting:

  • Less "fork this to start a plugin"

  • More "use this when you need patterns for starting files — generating from templates, wiring up file watchers, kicking off a structured note from a command"

The on-disk rename happened during the content-farm pseudomonorepo cleanup. The GitHub remote URL is still obsidian-plugin-starter.git until we do the GitHub-side rename.

What this enabled

Everything that came after this commit in the farm — the wide-modal layout in image-gin, perplexed, lmstud-yo, plunk-it; the callout-handling code in cite-wide; the manifest scaffolding pattern across the board — leans on what landed here. The patterns are still load-bearing even as the "starter plugin" mission winds down.

Retrospective notes

  • Written 2026-05-04, seven months after the founding commit.

  • The simplest history in the farm: one commit, perfectly stable. Exactly what a starter should be.

  • Future updates should be additive, not breaking — backporting patterns that proved themselves downstream.

  • The "we built this because Obsidian's official starter is too simple to be useful" framing is honest. We're not the only ones who think so; we're just one of the ones who wrote a better one.