I document almost everything I do in reStructuredText: business processes, technical procedures, how-to guides, project plans, and the notes behind every system I run. I've worked that way for years, ever since I ran into the limits of Markdown. So when I couldn't count on a reStructuredText preview in my JetBrains IDE, I built one and published it, free and open source, for the other people who rely on the format too.
This is why a file format matters that much to me, what the plugin does, and what keeping it working has taught me.
Why reStructuredText instead of Markdown
Markdown is great for a README or a quick note. It gets harder when documentation becomes a system: hundreds of pages across many projects that have to link to each other, stay consistent, and build into something people can actually search.
reStructuredText and Sphinx were designed for that job. These are the parts I use every day:
- Labels and cross-references. Every section I write gets a label, so any document can link to it by name. When a reference breaks, the Sphinx build warns me instead of quietly shipping a dead link.
- Directives. Notes, warnings, code blocks, tables of contents, and included files are part of the language itself, not an extension that only some tools understand.
- One specification. Markdown comes in many dialects that disagree at the edges. reStructuredText has one, and Sphinx builds it the same way every time.
- Documentation hubs. Sphinx can pull the documentation from many separate projects into one searchable site, which is how I keep my own work organized.
There's a newer reason too. The AI agents I work with read project documentation before they change anything. Clear, structured docs make their work better, which makes documentation part of the system rather than paperwork about it.
What was missing
JetBrains IDEs understand reStructuredText, but the built-in preview renders through the Python plugin. PhpStorm, my main IDE, doesn't offer the Python plugin, and plenty of people in IntelliJ IDEA, WebStorm, and other JetBrains IDEs don't want the whole Python stack just to see a rendered page.
For most developers that's a small gap. For someone writing documentation all day, working without a live preview means finding formatting and cross-reference mistakes only after the build, instead of while typing.
What the plugin does
ReStructuredText Preview (Standalone) skips the Python plugin entirely. It calls rst2html from docutils, the reference implementation of reStructuredText, and shows the rendered page next to the source inside the IDE.
- A split editor with the source on one side and a live preview on the other, updated as you type
- Scrolling kept in sync in both directions
- Syntax-highlighted code blocks and math rendered as MathML
- Styled notes and warnings, light and dark themes, and printing straight from the preview
- Automatic detection of
rst2html, including pyenv installs, with a setting to point at a specific one
The preview renders in the IDE's embedded Chromium browser, with a simpler Swing renderer as a fallback where that browser isn't available. It works in any JetBrains IDE from 2024.3 onward.
What maintaining it has taught me
Publishing a plugin is the easy part. Keeping it working as the platform moves is the real job.
- The platform moves under you. In the 2026.2 releases, JetBrains moved the embedded browser out of the core platform and into a bundled plugin. Without a change, the preview would have failed to load. Version 1.2.1 declares that dependency explicitly and falls back to the Swing renderer if the browser is missing.
- Test against the oldest and the newest. Every build is verified against both the oldest supported IDE release and the newest one, and releases publish to the Marketplace automatically through GitHub Actions.
- Feedback loops hide in small features. Synchronized scrolling felt jerky because the two panes kept correcting each other: the preview moved the editor, the editor pushed the preview back, and a timer dropped some of the user's own scroll events in between. The fix was to let whichever pane you're actually scrolling own the synchronization.
None of that is unusual. It's the same work every system needs: watch what changes underneath you, verify against reality, and fix causes rather than symptoms.
Why give it away
The people who depend on reStructuredText inside JetBrains IDEs are a small group, and small groups tend to get left behind when a vendor's priorities shift. I built the plugin for my own work and published it for the few people like me who rely on the format too. As of September 2026 it has been downloaded more than 560 times.
If you write reStructuredText in PhpStorm, IntelliJ IDEA, PyCharm, WebStorm, or another JetBrains IDE, you can install it from the JetBrains Marketplace. The code is on GitHub under the Apache 2.0 license, and issues and pull requests are welcome.
It's also a fair picture of how I work: when a tool I depend on breaks, I find the layer where it broke, fix it there, and leave the documentation behind.