Post

Update on reStructuredText and Visual Studio Code

When I started the reStructuredText extension for Visual Studio Code in Nov 2015, I wasn’t expect it to be a hot extension in the gallery. But even without an ambition, now it serves >1,700 users, so time to make it better.

Interestingly that more people enter the arena with their reStructuredText extension, like this one starting in Feb 2016, and this one adding reStructuredText support in Jun 2016.

As all of them provides preview, below I make a comparison,

Extensionvscode-restructuredtextRST-vscodepreview-vscode
Technologysphinxdocutilsrst2mdown
EffectMost accurateSomewhat usefulHard to predict

So why rst2mdown might give unpredictable result? reStructuredText has a far richer syntax than Markdown. Therefore, when you convert to Markdown, information lost happens, and the final preview result can be completely different.

Why cannot docutil achieve the best result? Because it only processes a single file, that included files and other features related to a complete sphinx project cannot be properly rendered.

As a result, only a true sphinx based solution like vscode-restructuredtext can offer the most accurate preview with full theme support.

To try out the best preview tool, you can download/upgrade to Visual Studio Code 1.3.0, and then follow the guide.

© Lex Li. All rights reserved. The code included is licensed under CC BY 4.0 unless otherwise noted.