MyST Reader

Render MyST Markdown directly in your Obsidian notes while keeping your Jupyter Book and Sphinx source unchanged. Designed for technical notes, equations, and multilingual course material, including Hebrew.

Install before community approval

1. Download main.js, manifest.json, and styles.css from the latest GitHub release, or extract the release ZIP.
2. Create <your vault>/.obsidian/plugins/myst-reader/ and put the three files directly inside it.
3. Restart Obsidian. Under Settings → Community plugins, enable MyST Reader. Community plugins must be allowed in your vault.
4. Open a Markdown note as usual. Supported MyST blocks render automatically in Reading view and Live Preview. No extra pane, ribbon button, or command is needed.

The folder must be called myst-reader. The plugin supports desktop and mobile APIs; a physical mobile device has not yet been tested.

Open a note as usual

In Live Preview, supported directives render as callouts, equations, or other preview blocks when the cursor is outside them. Move the cursor into a block or use its Edit button to expose the source. Source mode always shows the original Markdown.

The separate pane from versions 1.0.0–1.0.2 has been removed. On upgrade, a saved legacy pane is closed if the same file is already open, or converted to a normal note if it was the only view of that file.

Example

```{admonition} מערכות LTI
:class: tip

$$T\{x(t)\}=x(t)\ast h(t)$$
$$x(t)\ast h(t)=\int_{-\infty}^{\infty}x(\tau)h(t-\tau)\,d\tau$$
```

The directive becomes a native tip callout containing rendered math. The source file is never rewritten.

Colon fences work in Live Preview:

::::{note} An outer note

:::{warning} Nested warning
Keep an eye on the units.
:::
::::

Supported syntax

• Admonitions: admonition, note, tip, hint, important, warning, caution, attention, danger, error, seealso, todo, topic, and sidebar.
• :class: tip and related admonition types; dropdown and :class: dropdown become collapsible callouts. :open: expands them initially.
• math, with :label: or :name: anchors; dollar math is handled by Obsidian's MathJax renderer.
• figure and image, with relative image paths, alt text, and figure captions.
• code, code-block, and code-cell display code. They never execute code.
• Simple list-table directives, with zero or one header row and one-line cells; table wraps a Markdown table.
• rubric, epigraph, and pull-quote.
• Top-level raw HTML, either inline or loaded with :file: from a vault HTML file relative to the current note. Scripts and HTTPS libraries run in an isolated iframe in both Reading view and Live Preview.
• Inline {math} / {m}, {code}, {file}, {command}, {kbd}, {guilabel}, {ref}, {eq}, {numref}, and {doc} roles. Explicit link text such as {ref}`See this <my-label>` is supported.
• Standalone (my-label)= labels inside processed directives.

See the demo note for a complete example.

Scope and limitations

This renderer supports a documented subset of MyST, not the complete MyST parser or a Jupyter/Sphinx runtime. Build your book with its normal toolchain for authoritative output.

Unknown directives and roles remain unchanged. Includes, non-HTML raw directives, nested raw HTML, notebook execution, bibliography resolution, Sphinx domains, tab sets, grids, YAML directive options, cross-document label indexing, automatic equation/figure numbering, and inline roles outside processed directives are not implemented. ref, eq, and numref create local anchor links and do not compute numbers. Image sizing and layout options are not implemented. Invalid or unclosed directives remain readable as source. Inline roles within indented code, fenced code, and frontmatter are preserved. More than 32 nested directive levels fall back to source.

Reading view can recover custom titles when Obsidian supplies source section information; otherwise it uses the directive's default title. Live Preview has the full source and custom titles.

Interactive HTML

```{raw} html
:file: interactives/frequency-response.html
```

The example reads interactives/frequency-response.html relative to the note's folder. The file must be inside the vault and end in .html or .htm. Changes to the HTML file reload its frame automatically. Missing or invalid files show an explanatory message.

HTML can contain inline JavaScript and load libraries from absolute HTTPS URLs. Fragments that reference MathJax or contain LaTeX delimiters automatically receive MathJax 3.2.2 from jsDelivr, unless they already include a MathJax script loader. This supplies the runtime normally provided by Jupyter Book. Internet access is needed for remote resources, including this math runtime; self-contained HTML can work offline. Relative companion assets are not resolved from the HTML file, so use self-contained content or absolute HTTPS URLs. The frame resizes to its content and retains scrolling for very long documents. Raw HTML formats other than html stay readable as source.

Privacy

MyST Reader does not write to notes, read files outside the vault, or collect telemetry. It reads HTML files explicitly referenced by raw directives. Raw HTML scripts execute inside an iframe with sandbox="allow-scripts" and without allow-same-origin; they cannot access Obsidian's DOM, vault APIs, or application storage. Only embed HTML you trust: its scripts and external resources can contact third-party servers, which receive ordinary network information such as your IP address. The iframe sends no referrer. Other Markdown rendering is delegated to Obsidian, including its ordinary handling of remote images and links. Code cells and code blocks remain display-only.

Development

Requires Node.js 22.18+ or 24+, npm, and Obsidian 1.7.2 or newer. The plugin uses public Obsidian APIs only; the development Node requirement does not apply to users installing the bundled plugin.

npm ci
npm run check
npm run package

npm run dev watches source changes. The CommonJS bundle is intentionally unminified for review. npm run package creates the three release assets under dist/myst-reader/; ZIP that directory for manual installation.

Release and community registration

The repository must be public with manifest.json, README.md, and LICENSE at its root. Create a GitHub release tagged exactly as the manifest's version (no v) and attach main.js, manifest.json, and styles.css. The included release workflow does this for a pushed version tag after running checks.

Submit through Obsidian Community using an Obsidian account linked to the repository owner's GitHub account. Community availability depends on Obsidian's review. See the official submission guide.

License

MIT. This is an independent implementation; it does not incorporate code from other MyST plugins.