sanity-plugin-md-notes

What it is

sanity-plugin-md-notes lets you drop a .help.md file next to any Sanity schema file. Editors then see a native help panel in the document inspector, the editor-pane view tab, and the kebab dialog, all driven by the same markdown file. The notes are version-controlled alongside the schema, so they stay in sync without a separate CMS or wiki.

The plugin is opt-in at the schema level. You wrap a schema with withHelp() once; help panels only appear for schemas that explicitly ask for them, even if a stray .help.md file exists nearby. This makes it safe to add to an existing studio without affecting documents that don't need help copy.

What you get

• One .help.md file drives three surfaces: inspector panel, view tab, and kebab dialog.
• Schema opt-in via withHelp() so panels never appear where you didn't intend them.
• GFM tables, fenced code blocks with copy buttons, admonitions, heading anchors, and inline video embeds for Loom, YouTube, Vimeo, and Wistia.
• Singleton-friendly helpers (helpDocument / helpView) for documents built via S.document().
• Bundler-agnostic: works with Vite, Webpack, and Turbopack via a CLI codegen step for the latter.
• The widest compatibility range of our plugins: Sanity Studio v3, v4, and v5, with React 18 or 19.
• An optional "Edit on GitHub" footer link, auto-detected from .git/config via the included Vite plugin.

How to use it

Install it from npm:

npm i sanity-plugin-md-notes

For a Vite-based Sanity studio, register the Vite plugin and then wire up helpPlugin and withHelpDefaultDocumentNode in sanity.config.ts:

// sanity.config.ts
import { defineConfig } from "sanity";
import { structureTool } from "sanity/structure";
import { helpPlugin, withHelpDefaultDocumentNode } from "sanity-plugin-md-notes";

const helpFiles = import.meta.glob("./schemaTypes/**/*.help.md", {
  eager: true,
  query: "?raw",
  import: "default",
}) as Record<string, string>;

export default defineConfig({
  plugins: [
    helpPlugin({ files: helpFiles }),
    structureTool({
      defaultDocumentNode: withHelpDefaultDocumentNode(),
    }),
  ],
});

For Next.js / Turbopack setups, the plugin ships a CLI that generates a file map at build time instead of using import.meta.glob. The README covers both paths in detail.

How we use it

Content models on real projects tend to accumulate edge cases that developers understand but editors don't. Putting that guidance in a wiki means it drifts out of date or never gets read. Keeping it in a .help.md file next to the schema puts it where the decision was made, in the same diff, and surfaces it exactly where the editor is working.