What Is an RST File? A Plain-English Guide to reStructuredText

RST is readable source text that a documentation parser turns into structured output

An .rst file contains reStructuredText, a lightweight markup language whose reference parser belongs to the Docutils project. It is written in an ordinary text editor, so the file can be reviewed in version control and searched without opening a word processor. Punctuation and indentation tell the parser what the writer meant: a heading, paragraph, list, literal block, link, footnote, table, directive, or reference. A rendering tool then makes HTML, LaTeX, man pages, or another output. The raw file is source material, not the final web page or PDF.

RST is common in Python documentation and Sphinx projects because it can express more than basic emphasis and headings. It has named hyperlink targets, citations, substitutions, field lists, directives, and interpreted-text roles. Sphinx adds its own domains and directives, including toctree for joining documents into navigation. That last detail matters: valid RST is not automatically valid project documentation. A file may parse in Docutils while still causing a Sphinx warning because it is absent from the project’s navigation tree.

Punctuation becomes structure only when the surrounding whitespace follows the grammar

Section titles use a line of repeated non-alphanumeric punctuation above and/or below the title. Docutils says the underline must be at least as long as the title text. The symbols themselves do not have universal fixed levels; their hierarchy comes from consistent use within a document. A line of four or more repeated punctuation characters, with blank lines around it and no title, is instead a transition. This is why a decorative row of dashes can unexpectedly become a structural element when placed in the wrong location.

Indentation is equally important. A nested list paragraph must align with the text after the list marker, not merely look approximately indented. A paragraph ending with :: introduces a literal block when followed by indented text. Backslashes escape markup characters, so \*word* shows literal asterisks rather than emphasis. Blank lines divide paragraphs and delimit many block constructs. These rules make source files predictable for a parser, but a single missing blank line or one extra space can change the document tree.

RST offers useful documentation features, with strict limits that should guide the choice

• Plain-text review: the source remains readable in a text editor and works well with line-based changes.
• Named references: hyperlinks, footnotes, citations, and substitutions can be reused, but each reference must resolve in the selected build.
• Rich blocks: directives can create images, code blocks, contents lists, and project-specific elements, but parser support is not universal.
• Two table syntaxes: simple tables are compact but cannot have row spans; grid tables are more complete but easier to damage by misalignment.
• Multiple outputs: one source can feed Sphinx or Docutils writers, yet typography and extensions differ by builder.
• No visual WYSIWYG guarantee: a source editor cannot prove the final theme, image path, cross-reference, or PDF pagination is correct.

RST is a strong choice when the project already builds with Docutils or Sphinx and needs cross-references, API docs, or generated navigation. It is not automatically a better replacement for every note or office document. A recipient who only needs fixed pages may need PDF; a team using a Markdown-only pipeline may need Markdown. The useful conversion is one that targets the parser and build system that will own the content next.

Docutils and Sphinx share syntax, while extensions make their compatibility boundaries visible

Docutils is the reference implementation for core reStructuredText. Sphinx builds on that syntax and supplies its own documentation features. Its toctree directive connects separate source files; Sphinx warns when a file in the source directory is not included because normal navigation cannot reach it. Sphinx also supports substitutions through configuration such as rst_prolog and rst_epilog, which can make markup work in one project but fail when copied into another without the same configuration.

Directives and roles are a frequent compatibility boundary. The Docutils specification says an unrecognised directive generates a level-3 error and the directive block is included as a literal block. Unknown roles also generate errors unless a role has been defined. Therefore, a page that renders correctly in a project with a Sphinx extension may show raw directive text or fail in a plain Docutils run. Build with the same toolchain and configuration used by publication rather than validating only in an editor preview.

Parser messages point to precise source mistakes more often than to a broken renderer

A title is treated as ordinary text or an unexpected section level. Check that the underline is at least as long as the title and that the punctuation style follows the document’s established hierarchy. Do not invent a new adornment halfway through a page. A consistent title map avoids a build that produces a plausible page with wrong navigation depth.

A list, code sample, or directive raises an indentation warning. Restore the required blank line and align continuation text with the first text after the bullet or directive marker. For literal blocks, make sure :: ends the preceding paragraph and the block is indented. Tabs can display differently across editors, so use spaces according to the project convention.

A directive appears literally or a role is unknown. The named feature is missing from the active parser or extension set. Check the spelling, enable the documented Sphinx extension if the project permits it, or rewrite with core RST. Do not silence the warning by leaving a literal directive in published output.

A table breaks after a small edit. In a simple table, spaces define column boundaries and the first column cannot be blank for a new row because that line is read as a continuation. Use a grid table when row spans or complex first-column content are necessary, then rebuild borders deliberately instead of adding random spaces.

RST source and rendered documentation solve different stages of the same publishing job

Questions that prevent a small RST edit from becoming a documentation build failure

Use the project’s normal build as the conversion test. Make a structural edit, run the build with warnings visible, read the source line named by the first warning, and then open the generated page. That distinguishes grammar errors from project errors such as a missing image path or a page that was never added to navigation. A clean build is evidence; viewing the delivered output remains the final check.

When moving a file between projects, inventory its images, substitutions, custom roles, directives, labels, and cross-references. A project-level configuration can make markup work in one repository and fail in another. Use core RST where possible or document the extension the destination requires. This prevents pages that quietly lose links, callouts, or reusable substitutions after a move.

For a multi-page manual, agree on one heading map before conversion. The punctuation choice matters less than using it consistently for document titles, sections, and lower levels. A shared map lets generated navigation show the intended hierarchy and stops decorative lines imported from a source document becoming accidental sections or transitions.

Is RST the same as Markdown?
No. Both are text markup formats, but RST has its own grammar and core features, and Sphinx adds project extensions.

Why is my heading not recognised?
Check the adornment length, blank lines, and consistency of the punctuation hierarchy.

Why did a directive print as code?
The parser did not recognise its handler. Use the right build configuration or replace it with supported core markup.

Can a simple table have row spans?
No. Docutils documents simple tables as limited; use a grid table when the structure requires row spans.

Why is a page missing from the Sphinx site?
Put it in a reachable toctree. Sphinx warns about source files that are not included in one.