MDX Preview

MDX Preview

Preview MDX files in Obsidian, with first-class support for Code Hike — scrollycoding, code annotations, focus lines, and compile-time syntax highlighting.

Forked from yulei-chen/obsidian-mdx and rewritten with a security-first architecture, mobile compatibility, and offline rendering.

Why this plugin

Most MDX-related plugins for Obsidian only handle editing — they register .mdx as a plain-text file so Obsidian stops treating it as unknown. None of them compile or render the MDX.

MDX Preview is the only plugin that compiles your MDX — JSX, React components, and Code Hike annotations all render correctly. Pair it with any of the edit-only plugins if you want richer editor support alongside the preview.

Why not the original MDX by yulei-chen? That plugin is the foundation this one was built on. This fork adds a security-first architecture (sandboxed iframe with a consent gate), bundles the renderer at build time so no internet connection is needed, and supports mobile.

Features

• Code Hike rendering — scrollycoding, !focus, !mark, !diff, and all Code Hike annotations work out of the box
• Compile-time syntax highlighting — powered by @code-hike/lighter (pure JavaScript, no native dependencies), so it works on iOS and Android
• Sandboxed execution — MDX JavaScript runs in a null-origin sandbox="allow-scripts" iframe with no access to your vault or Obsidian APIs
• Session consent gate — you confirm once per session before any MDX JavaScript runs
• Offline — the renderer is bundled at build time; no CDN calls are made at runtime
• Auto-open — .mdx files open directly in the preview view, no command palette step needed
• Debounced live reload — preview updates 400 ms after you stop typing

Installation

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them into .obsidian/plugins/mdx-preview/ inside your vault.
3. Enable the plugin in Settings → Community Plugins → Installed Plugins.

Community plugin browser

Once listed, search for MDX Preview in Settings → Community Plugins → Browse and click Install.

Usage

1. Create or open any file with a .mdx extension — it opens automatically in the preview view.
2. On first open, click Enable MDX Preview in the consent banner. MDX files contain executable JavaScript; the plugin asks once per session before rendering.
3. Edit the file in a separate pane (source mode recommended) and the preview updates as you type.

Code Hike example

Copy this into a .mdx file to try Code Hike annotations:

export function Code({ codeblock }) {
  return <pre>{codeblock.value}</pre>
}

## Annotated code

```js !focus
// !mark[/greet/] red
function greet(name) {
  // !mark green
  return `Hello, ${name}!`
}
```

For a full scrollycoding example, see the Code Hike vite example.

Security model

MDX is executable JavaScript. This plugin takes several steps to limit the blast radius:

• The iframe uses sandbox="allow-scripts" with no allow-same-origin, giving it a null origin — vault files and Obsidian APIs are completely unreachable from inside the iframe
• No eval() or new Function() is used — the compiled MDX function body is embedded directly as a <script> tag, which is the same model browsers use for normal scripts
• The consent gate resets on every Obsidian restart, so you are always in control of when MDX JavaScript runs
• Outbound network requests from inside the iframe are still possible (this is a browser constraint, not something a plugin can block). Only preview files you trust.

Contributing

Issues and pull requests are welcome at jovialio/obsidian-mdx.

Credits

Originally forked from yulei-chen/obsidian-mdx by yulei-chen. Thank you for the foundation.

License

MIT — see the LICENSE file for details.