RST preview

VS Code Stable

ubCode provides a real-time RST preview that is synchronized with the editor:

A lot of markup problems cannot be detected in a continuous integration system as most input is valid RST in principle, it is just not what the user intended.

The RST preview shows the user instantly how the RST will be parsed by Sphinx. The preview is a great way to learn RST syntax and to see how the RST will be rendered by Sphinx. The goal is not to replace the final Sphinx HTML output, but to get early insights whether the written RST code is as expected.

Code blocks are coloured by the same engine the builds use, so a code block is coloured by the same grammar and the same classes as the site and the PDF.

Preview modes

The preview renders in one of two modes, switched live from the preview toolbar or set initially with the ubcode.preview.mode setting (rendered or structural; default rendered):

Rendered

The default. Every construct renders as its semantic HTML shape — headings, lists, tables, admonitions, need cards, and so on — and hydration (see below) is active.

Structural

A “show me what was parsed” view. Every directive and role renders as a uniform placeholder showing its name, arguments, options, and body, identically for reStructuredText and MyST. Reach for this when you want to confirm how your source was parsed rather than how it will look.

The Writing pages describe what the Rendered mode shows.

Hydration

Some of what the preview shows depends on the rest of your project, so it is filled in — hydrated — from the background index once indexing completes, and refreshed after each subsequent indexing pass (near-real-time and bounded, not on every keystroke). Until the first pass finishes, the preview still renders from the source in front of it: cross-references appear as placeholder chips and need cards show only the fields written directly in the directive. See Need cards below for how a need card is hydrated.

Element

Before hydration

After hydration

Cross-reference

A placeholder chip naming the target.

A clickable link that opens the referenced target.

Need card

The fields written directly in the directive.

The effective, post-needextend field values, plus a “links back” list of incoming links.

Need cards

A need-type directive (a req / spec / … from your needs.types) renders in the preview as a need card: a header with the need’s type, title, and id, a meta table of its fields and links, and the need’s body.

Once the project has been indexed in the background, the card is hydrated to show the need as it will actually build:

  • field values reflect any needextend applied elsewhere in the project (so the card shows the effective, post-extend value, not just the source directive);

  • each outgoing link becomes a clickable cross-reference that navigates to the linked need’s location;

  • a “links back” section lists the incoming links — the needs that link to this one — data that does not appear in the source file at all.

Until the index is available the card still renders, using the field values written directly in the directive, with its links as plain text; the hydrated data appears on the next update once indexing completes.

The hydrated meta table shows your authored fields plus anything needextend changed — not every config-default field that a full Sphinx-Needs build would list. This keeps the authored rows visible rather than buried; see Differences from a Sphinx build for the full comparison.

See also