Authoring

This section is a reference for writing reStructuredText and Markdown (MyST) content that the ubCode preview — and the tooling built around it — understands: what renders richly as its final shape, what renders as a self-describing placeholder, and where the preview deliberately differs from a full Sphinx build.

It is not a syntax tutorial. For the language itself, see the Sphinx reStructuredText primer and the directives reference. For the preview feature itself — the synchronized, real-time panel in the editor — see RST preview: its job is to give you early insight into how your markup will be parsed, not to reproduce the final Sphinx HTML output.

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 rest of this section describes the Rendered mode.

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 RST preview for more on need cards and hydration.

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.

How to read this section

Each page describes what the preview renders for one family of markup:

  • Directives — block constructs such as admonitions, tables, and code blocks, and which ones fall back to a placeholder.

  • Roles — inline roles such as cross-references, :kbd:, and your own custom roles.

  • Needs — need directives and how they render as need cards.

  • Variants — the if directive, the variant role, and variant field values.

  • Diagrams — Mermaid and PlantUML diagram directives.

  • Markdown (MyST) — writing content in Markdown rather than reStructuredText, and how it maps to the same preview.

  • Differences from a Sphinx build — the full register of where the preview and a real build diverge.