# sanity-plugin-md-notes

> Our MIT-licensed Sanity plugin that turns a .help.md file next to any schema into a native help panel for editors.

**Category:** plugin | **License:** MIT | **Updated:** 2026-08-19

## Install

```bash
npm i sanity-plugin-md-notes
```

## Links

- Package: https://www.npmjs.com/package/sanity-plugin-md-notes
- Related service: /services/sanity

---

## 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:

```bash
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`:

```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.