Markdown and Properties
Extend Markdown rendering, callouts, plugin-scoped styles, and note property types.
Markdown rules, callouts, and property types are declared under contributes and need no
permission. They are registered when the plugin is enabled (rendering needs them before any command
runs) and removed when it is disabled.
Inline Replacements#
settings: { replaceTickets: { type: "boolean", label: "Link tickets", default: true },},contributes: { markdown: { inline: [ { id: "ticket", pattern: "APP-(\\d+)", flags: "g", when: "replaceTickets", replacement: { type: "text", content: (match) => `Ticket ${match[1]}` }, }, ], },},pattern is a regex source string without delimiters. when names a boolean setting: the rule is
active only while that setting is true, and toggles live when the user changes it. Inline rules
are lightweight and shared by editor and renderer consumers.
Semantic Transforms#
Use semantic rules when output should work across Live Preview, Reading View, and export. Output must be portable nodes (text, container, span, link, image, code), not arbitrary DOM.
markdown: { semantic: [ { id: "ticket-links", selector: { type: "text" }, priority: 10, transform: ({ node }) => (node.type === "text" && node.value.includes("APP-") ? node : null), }, ],},Callout Types#
markdown: { callouts: [ { type: "decision", aliases: ["decide"], label: "Decision", color: "var(--accent)", backgroundColor: "var(--accent-subtle)", }, ],},Later registrations win. Disabling the plugin restores the previous definition.
Preprocessors and Unified Processors#
markdown.preprocessors and markdown.processors run only on reading-view and export:
markdown: { preprocessors: [ { id: "append-footer", surfaces: ["reading-view"], preprocess: (markdown) => `${markdown}\n\n---\nRendered by plugin.`, }, ],},Live Preview integrations should use inline rules, semantic rules, callouts, fold providers, or
editorExtensions instead.
Plugin styles.css#
A plugin may ship a root styles.css only when it declares contributes.markdown. Otherwise the
plugin fails to load.
Plugin CSS is scoped to .markdown-surface. Selectors that do not already target
.markdown-surface are prefixed by the host. Selectors that escape the Markdown surface with
sibling combinators are rejected.
Allowed at-rules:
@container@layer@media@supports
Blocked at-rules include @font-face, @import, @keyframes, @namespace, and @page.
Property Types#
contributes: { propertyTypes: [ { type: "rating", baseType: "number", displayName: "Rating", icon: "star", deserialize: (value) => Number(value ?? 0), serialize: (value) => Number(value ?? 0), validate: (value) => ({ valid: typeof value === "number" && value >= 0 && value <= 5, message: "Rating must be between 0 and 5", }), }, ],},Property type ids are namespaced internally as <plugin-id>:<type>.