Scoping

Config resolves from broad defaults to local overrides:

1plugin -> collection -> field/block scope -> direct renderer props

Later layers win for scalar values. Class names are joined so global and collection class additions can both apply.

Plugin Defaults

1payloadMarkdown({2  code: {3    lineNumbers: true,4    shikiTheme: 'github-dark',5  },6  config: {7    size: 'lg',8    variant: 'blog',9  },10  themes: {11    card: {12      items: [13        {14          name: 'brand',15          classes: 'rounded-2xl border border-cyan-400/40 bg-cyan-950/30 p-5',16        },17      ],18    },19  },20})

These defaults apply everywhere unless a collection or renderer overrides them.

Collection Overrides

1payloadMarkdown({2  code: {3    lineNumbers: true,4  },5  collections: {6    posts: {7      code: {8        lineNumbers: false,9      },10      config: {11        className: 'posts-markdown',12        variant: 'docs',13      },14      themes: {15        card: {16          items: [17            {18              name: 'brand',19              classes: 'rounded-2xl border border-emerald-400/40 bg-emerald-950/30 p-5',20            },21          ],22        },23      },24    },25  },26  config: {27    className: 'global-markdown',28    variant: 'blog',29  },30})

For posts, the resolved className becomes global-markdown posts-markdown, while variant becomes docs.

Field And Block Scope

Use field and blocks when the same collection needs different presentation:

1payloadMarkdown({2  collections: {3    pages: {4      config: {5        blocks: {6          size: 'md',7          variant: 'docs',8        },9        field: {10          size: 'lg',11          variant: 'blog',12        },13      },14    },15  },16})

MarkdownRenderer defaults to field scope. MarkdownBlockComponent uses block scope.

Direct Rendering

1<MarkdownRenderer2  collectionSlug="posts"3  markdown={post.content}4  scope="field"5/>

Without collectionSlug, collection-scoped config cannot be resolved.

Renderer Overrides

1<MarkdownRenderer2  collectionSlug="posts"3  code={{ lineNumbers: true }}4  markdown={post.content}5  themes={{6    callout: {7      items: [8        {9          name: 'preview',10          classes: 'rounded-xl border border-amber-400/40 bg-amber-950/20 px-4 py-3',11        },12      ],13    },14  }}15  variant="compact"16/>

Use local overrides for preview states, one-off pages, tests, or migration paths. Prefer plugin and collection config for repeatable production behavior.

Theme Merge Behavior

Theme groups merge by theme name. A collection theme with the same name as a global theme overrides that global theme for the collection.