Diagnostics

remark-to-comark check and the Vite Doctor extension report these codes. Warnings are work left. Info findings say what each plugin becomes.

To teach an agent Comark's blocks and plugins, run npx skills add onmax/comark-ui.

A framework owns the remark setup (Astro, Next.js MDX, Contentlayer, Docusaurus, Gatsby, Velite, Nuxt). The framework calls remark, so rewrite can't change it. Where the framework lets you, render the Markdown yourself with renderHtml(markdown, comarkOptions()), such as in an Astro content loader or a Next.js route. Nuxt has @comark/nuxt. Otherwise keep remark for that site.

The same code covers react-markdown's remarkPlugins and rehypePlugins. Swap the component for <Markdown> from @comark/react or @comark/vue, with the Comark plugins the findings name.

A comark-ui package replaces the plugin. Its markup differs from the remark plugin's, so check any CSS that styled the old markup. If a port with identical output exists too, the finding names it.

Covered. Comark or comarkOptions() already does what the plugin did, such as GFM, frontmatter, raw HTML, and heading ids. Nothing to do.

A port in remark-to-comark/plugins replaces the plugin, with the same options: slug, autolinkHeadings, externalLinks, unwrapImages, squeezeParagraphs, npm2yarn, or readingTime. Each port's tests compare its HTML with the original's.

Your own plugin, or a plugin list the scan can't follow, such as a ternary or a function call. Port it to a Comark plugin, a post hook that walks state.tree.nodes, where an element is [tag, attributes, ...children]. The ports in remark-to-comark/plugins are short examples. Then compare the HTML of a few pages rendered both ways.

No Comark counterpart. The finding says why. A plugin that only touches the final HTML, like a minifier, can keep running on Comark's HTML. Anything else needs a port, and the plugin's test fixtures are the spec.

A lint plugin. Lint Comark documents with comark-linter, as a CLI or a Vite Doctor extension.

A unified chain rewrite can't replace without changing what it does. The finding names the reason. Port a plugin with no counterpart first, write HTML options as literals, and change callbacks, VFile reads, object inputs, and CommonJS by hand. A chain that ends in .parse() or .run() works on the syntax tree, so keep remark for it or port that code to the nodes parseMarkdown() returns.

A unified chain rewrite can replace with renderHtml(markdown, comarkOptions({ plugins })). Run remark-to-comark rewrite <dir> --write, then install @comark/html and the other packages it imports.

MDX is left alone, because expressions and imports need a JavaScript runtime. JSX that only passes props maps to Comark components, so <Callout type="tip"> becomes ::callout{type="tip"}. To convert a page by hand, rename it to .md, run remark-to-comark content on it while it's still plain prose, then add the components. Running content after that would escape them. Keep MDX for pages that run code.

Docusaurus v3 compiles .md as MDX too, unless docusaurus.config sets markdown: { format: "detect" }. If those files have no JSX, set it, check that the site builds, and run the check again.

Markdown Comark would read differently, such as braces, brackets, and :name that Comark reads as attributes, spans, or components, single-tilde strikethrough, and bare [label] references. Run remark-to-comark content <file> --write. remark still renders the file exactly as before.

Left as written, because no edit keeps remark's output the same. Comark may read it differently. Fix it by hand, then run the check again.

• A URL after an unclosed [. Escape the [ where it's plain text, or wrap the URL in <…>.
• A strikethrough inside another one (~a~~b~~a~) or inside a reference label ([~a~]). Rewrite it with ~~.

The same code skips a whole document when:

• Setups in its package or framework config disagree about syntax. Migrate it with the settings of the renderer that owns it.
• A plugin list isn't static, such as remarkPlugins={getPlugins()} or [enabled && gfm]. Use imported plugins, [plugin] tuples, or a local const array that nothing changes, exports, or passes on.
• A syntax plugin has options, such as [gfm, { singleTilde: false }]. Migrate it by hand with those settings.