Skip to content
Cortex

Markdown and Properties

Extend Markdown rendering, callouts, plugin-scoped styles, and note property types.

2 min readEdit on GitHub

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#

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

ts
markdown: {	semantic: [		{			id: "ticket-links",			selector: { type: "text" },			priority: 10,			transform: ({ node }) => (node.type === "text" && node.value.includes("APP-") ? node : null),		},	],},

Callout Types#

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

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

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

Search docs

Search Cortex documentation pages and headings.