sanity-plugin-tnd-docs

A Sanity Studio v3 plugin for displaying markdown documentation directly in your studio.

Installation

npm install sanity-plugin-tnd-docs

Usage

Add the plugin to your sanity.config.ts (or .js):

import { defineConfig } from 'sanity'
import { tndDocs } from 'sanity-plugin-tnd-docs'

// Import your markdown files using Vite's import.meta.glob
const docs = import.meta.glob('/docs/**/*.md', { eager: true, query: '?raw', import: 'default'})

export default defineConfig({
  // ...
  plugins: [
    tndDocs({
      documents: docs
    })
  ]
})

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | documents | Record<string, string> | Yes | - | Markdown files loaded via import.meta.glob | | name | string | No | 'tnd-docs' | Internal name for the tool. Will determine route in studio | | title | string | No | 'Documentation' | Display title in Sanity Studio | | variables | Record<string, string> | No | - | Key/value pairs for variable substitution in Markdown content |

Setting Up Your Documentation Files

1. Create a docs folder in your project

your-sanity-project/
├── docs/
│   ├── getting-started.md
│   ├── endpoints.md
│   ├── authentication.md
│   └── guides.md

2. Import markdown files

The plugin uses Vite's import.meta.glob to load markdown files at build time. This must be done in your sanity.config.ts:

// Load all .md files from the /docs directory
const docs = import.meta.glob('/docs/**/*.md', {
  eager: true,
  query: '?raw',
  import: 'default'
})

Example: Complete Configuration

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { tndDocs } from 'sanity-plugin-tnd-docs'

// Load documentation files
const docs = import.meta.glob('/docs/**/*.md', { eager: true, as: 'raw' })

export default defineConfig({
  name: 'default',
  title: 'My Project',

  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    structureTool(),
    tndDocs({
      title: 'Project Docs',
      documents: docs
    })
  ],

  schema: {
    types: [/* your schemas */]
  }
})

⚠️ The glob pattern must be a literal string - you cannot use variables:

// ✅ Correct
const docs = import.meta.glob('/docs/**/*.md', { eager: true, as: 'raw' })

// ❌ Incorrect - will not work
const path = '/docs/**/*.md'
const docs = import.meta.glob(path, { eager: true, as: 'raw' })

Markdown Syntax

Useful frontmatter

Currently the only frontmatter needed is:

| Name | Type | Required | Description | |--------|------|----------|-------------| | title | number | No | Will be used to populate the title of the entry in the side navigation. If missing, the path will be used | | weight | string | No | Will be used to sort the entries in the side navigation | | description | string | No | Will be printed in small text in the navigation entry |

Images

Sanity will copy the static directory as is, so you should use it to store your md images.

![This is the title attribute](/static/uploads/title-formating.png "This is a caption")

Variable Substitution

You can define reusable variables in the plugin config and reference them anywhere in your Markdown, including inside HTML attributes where standard Markdown reference links don't work.

tndDocs({
  documents: docs,
  variables: {
    cdn: 'https://your-cdn-url.example.com',
  }
})

Use {{variableName}} syntax in your Markdown files:

![Screenshot]({{cdn}}/images/screenshot.png)

<video>
  <source src="{{cdn}}/videos/demo.mp4" type="video/mp4">
</video>

Unknown variables (no matching key in config) are left unchanged.

License

MIT © The New Dynamic

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.