Skip to content
| Marketplace
Sign in
Visual Studio Code>Programming Languages>reStructuredText Preview (docutils)New to Visual Studio Code? Get it now.
reStructuredText Preview (docutils)

reStructuredText Preview (docutils)

Vereshchak

|
1 install
| (0) | Free
Accurate live preview for reStructuredText, rendered by docutils, with Sphinx and Zephyr roles and directives, scroll sync and syntax highlighting.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

reStructuredText Preview (docutils)

A live side-by-side preview for .rst files. Rendering is done by real docutils, the reference reStructuredText implementation, so the preview matches what Sphinx produces for core reST. The Sphinx and Zephyr roles and directives that plain docutils doesn't know are handled too, so Sphinx project docs (such as Zephyr's README.rst files) look right instead of showing error boxes.

Features

  • Live preview that updates as you type and keeps its scroll position.
  • Scroll sync in both directions; double-click in the preview to jump to that line in the source.
  • Previews are restored after VS Code restarts.
  • Syntax highlighting with Pygments, coloured for light, dark and high-contrast themes.
  • Problems shown in place: real reST mistakes (bad indentation, short title underlines, unknown targets) appear where they happen and are listed under the document, so you can catch them before sending a docs change.

Sphinx and Zephyr support

Construct Preview
code-block, sourcecode, code (any Sphinx options) Highlighted; unknown lexers (e.g. kconfig) shown as plain text
literalinclude with :lines:, :start-at:/:start-after:, :end-at:/:end-before:, :dedent:, :linenos: File included and highlighted
:ref:, :doc:, :term:, :zephyr:code-sample: Link title (Title <target> → Title)
:c:func:, :kconfig:option:, :dtcompatible:, any domain:role Symbol shown as code
:kbd:, :guilabel:, :menuselection:, :file:, :samp: Styled inline
:zephyr_file: / :zephyr_raw: Link to the file on GitHub
zephyr:code-sample Header card with name, description and relevant API
zephyr-app-commands Zephyr's own directive, loaded from the Zephyr tree the file is in (trusted workspaces only); a built-in approximation otherwise
tabs / tab / group-tab Each tab shown in order with its label
Anything else unknown Content still rendered in a dashed box and listed under "Shown approximately"

Usage

Open a .rst file, then use any of:

  • the preview button in the editor title bar (Alt+click opens it in the same column),
  • right-click the editor tab, the editor, or the file in the Explorer,
  • the Command Palette (Ctrl+Shift+P): reStructuredText: Open Preview or Open Preview to the Side,
  • Ctrl+Shift+V (preview) or Ctrl+K V (preview to the side).
Command What it does
reStructuredText: Open Preview Preview in the current column
reStructuredText: Open Preview to the Side Preview next to the editor
reStructuredText: Show Source From a preview, go to its .rst file
reStructuredText: Refresh Preview Render the active preview again
reStructuredText: Restart Renderer Restart the Python renderer process
reStructuredText: Show Renderer Log Open the extension's output channel

Settings

Setting Default Description
rstPreview.scrollSync true Keep the preview and the editor scrolled to the same place
rstPreview.pythonPath "" A Python with docutils and Pygments; empty means the extension manages its own environment

Requirements

Python 3.9 or newer on PATH. On first use the extension creates a private virtual environment in its storage folder and installs the pinned docutils and Pygments versions (one download from PyPI). Your project environments are not touched. To use an interpreter of your own instead, set rstPreview.pythonPath.

In untrusted workspaces the preview never runs code from the workspace.

Development

npm install
npm run compile

Press F5 in this folder to launch an Extension Development Host.

  • src/extension.ts: commands, preview panels, scroll sync, restoring previews, the managed Python environment, and the renderer process (JSON lines over stdio).
  • media/preview.js: the webview side: content updates, scroll mapping via data-line markers, in-page links.
  • python/rst_render.py: docutils rendering, Sphinx/Zephyr roles and directives, line markers, fallbacks.
  • python/audit.py <dir>: renders every README.rst under a folder and reports fallbacks and warnings. On the Zephyr tree, 795 of 823 render with no fallback or warning; the rest contain genuine reST errors, plus two graphviz diagrams.
  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft