T-Z6X5-obsidian-md-plugins-subpath

State: closed/done · Impact: medium · Complexity: small

Goal

Consumers that want only the remark plugins (obsidian-astro, any Astro docs site) pull the whole render stack today, and every consumer installs mermaid and katex even though only two Vue components import them, dynamically. This task adds a ./plugins subpath export and moves mermaid and katex to optional peers, which also lets viewers keep them out of the main chunk.

Today

Location	Role today
packages/ts/obsidian-md/package.json	exports: ., ./vue, ./theme.css; katex and mermaid in dependencies
packages/ts/obsidian-md/src/index.ts	Vue-free root; re-exports every plugin from src/plugins/*.ts
packages/ts/obsidian-md/src/plugins/	15 remark/rehype plugin modules
packages/ts/obsidian-md/src/vue/components/MathBlock.ts	await import('katex')
packages/ts/obsidian-md/src/vue/components/MermaidBlock.ts	await import('mermaid')
packages/ts/obsidian-md/README.md	Package docs
solutions/determined/packages/obsidian-astro/src/remark-wikilinks.ts	Imports remarkWikilinks from the root export
solutions/determined/packages/obsidian-astro/package.json	Depends on @sksizer/obsidian-md
solutions/determined/experiences/notes/nuxt.config.ts	Resolves katex/dist/katex.min.css from obsidian-md’s require context
solutions/ontological/desktop/src-nuxt/package.json	file:-wired consumer; installs obsidian-md’s dependencies

Proposed

package.json gains "./plugins": "./src/plugins/index.ts", a new barrel re-exporting the plugin functions and their option types; the root export keeps re-exporting them so no consumer breaks. katex and mermaid move to peerDependencies with peerDependenciesMeta.optional. Hosts that render math or diagrams declare them: the markdown-ui layer does so for every layer consumer, and the SDF host does so in its file:-wired package.json. obsidian-astro imports from @sksizer/obsidian-md/plugins. The README documents both.

Approach

1. Add src/plugins/index.ts; add the export; keep root re-exports.
2. Move katex and mermaid to optional peers; MathBlock.ts and MermaidBlock.ts catch a failed dynamic import and fall back to the source pre with a one-line console warning.
3. Declare katex and mermaid where the Vue components are used: packages/ts/markdown-ui (if T-A0HT-md-ui-layer-skeleton has landed) or solutions/determined/experiences/notes (if not), and solutions/ontological/desktop/src-nuxt. Point notes’ katex.min.css resolution at the package that now declares katex.
4. obsidian-astro: import from /plugins.
5. Root bun install; cd solutions/ontological/desktop && bun install; bun install --frozen-lockfile in both.
6. Verify: bun test and tsc --noEmit in packages/ts/obsidian-md; bun test in obsidian-astro; moon run product-workbench:check sdf:check; a note with $x$ and a mermaid fence still renders; moon run :check :test --affected.

Files to touch

Location	Kind	Change
packages/ts/obsidian-md/package.json	modify	./plugins export; peers
packages/ts/obsidian-md/src/plugins/index.ts	new	Plugin barrel
packages/ts/obsidian-md/src/vue/components/MathBlock.ts	modify	Fallback when katex is absent
packages/ts/obsidian-md/src/vue/components/MermaidBlock.ts	modify	Fallback when mermaid is absent
packages/ts/obsidian-md/README.md	modify	Document the subpath and the optional peers
solutions/determined/packages/obsidian-astro/src/remark-wikilinks.ts	modify	Import from /plugins
solutions/determined/experiences/notes/nuxt.config.ts	modify	katex.min.css resolved from the declaring package
solutions/determined/experiences/notes/package.json	modify	Declare katex, mermaid if the layer has not landed
solutions/ontological/desktop/src-nuxt/package.json	modify	Declare katex, mermaid
solutions/ontological/desktop/bun.lock	modify	Regenerated
bun.lock	modify	Root lockfile regen

Acceptance criteria

• AC-1: packages/ts/obsidian-md/package.json has a ./plugins export and lists neither katex nor mermaid under dependencies.
• AC-2: import { remarkWikilinks } from '@sksizer/obsidian-md/plugins' typechecks from obsidian-astro, and grep -rn "from '@sksizer/obsidian-md'" solutions/determined/packages/obsidian-astro/src returns nothing.
• AC-3: bun test and tsc --noEmit pass in packages/ts/obsidian-md; bun test passes in solutions/determined/packages/obsidian-astro.
• AC-4: moon run product-workbench:check and moon run sdf:check pass, and a note with inline math and a mermaid fence renders both in the notes product.
• AC-5: bun install --frozen-lockfile passes at the root and in solutions/ontological/desktop.

Out of scope

• Splitting the package or publishing it outward.
• Moving shiki; it is already behind a dynamic import and is a real dependency of the root pipeline.
• The obsidian-astro slug resolver; only its import path changes.

Dependencies

• Ordering, not a hard dependency: after T-A0HT-md-ui-layer-skeleton the layer is the natural home for the katex and mermaid declarations and the katex.min.css resolution; before it, notes carries them.
• D-7VMX-markdown-ecosystem-strategy: plugins stay the one implementation of the dialect; the subpath exposes them without a second copy.

Discovery context

Member of milestone M-931L; promoted from backlog item B-Z6X5-obsidian-md-plugins-subpath; folded into the roster of D-K3EM-markdown-editor-chrome-and-plugin-environment.

---

← Back to Tasks