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,

Extension	vscode-restructuredtext	RST-vscode	preview-vscode
Technology	sphinx	docutils	rst2mdown
Effect	Most accurate	Somewhat useful	Hard 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 docutils 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.