RST File Format (.rst)

An RST file holds reStructuredText, the markup David Goodger designed in 2001 for Python documentation, where directives and interpreted text roles extend the syntax with cross-references, footnotes and generated content that Markdown has no built-in equivalent for.

.rstDocuments

RST at a glance#

Full name	reStructuredText
File extension	.rst
Category	Documents
Developer	David Goodger
First released	2001
MIME types	text/x-rsttext/prs.fallenstein.rst
Compression	Uncompressed
Specification	reStructuredText Markup Specification
FileFlip support	FileFlip reads and writes this format

What a .rst file can hold#

These are the things a RST file either supports or does not, and they are what decides whether a conversion keeps everything or quietly drops something.

Selectable text	Yes
Human readable	Yes
Comments	Yes

Strengths and limitations of RST#

What RST does well

Directives are a real extension mechanism, so a Sphinx project adds custom block types like code-block or toctree without inventing new punctuation
Stricter and less ambiguous than Markdown, since Docutils enforces one grammar and one reference parser
PEP 287 made it the standard for Python docstrings, so most Python documentation tooling reads it natively

Where RST falls short

Directive syntax (.. directive:: value) is more verbose than Markdown's punctuation-based shortcuts
Almost all mainstream tooling outside the Python and Sphinx ecosystem expects Markdown instead
Significant whitespace and strict indentation rules make hand-editing less forgiving than Markdown

Write in reStructuredText for Python documentation or any Sphinx-built site that needs directives, cross-references and generated indexes.

Convert reStructuredText to Markdown when the destination lives outside the Sphinx or Python ecosystem, since most directives don't have a Markdown equivalent.

How to open a .rst file#

A .rst file opens in the programs below, grouped by the platform you are on. If you would rather not install anything, FileFlip converts RST into a format your machine already opens, and it does it in the browser tab rather than on a server.

Platform	Programs that open it
Windows	VS Code (reStructuredText extension), PyCharm
macOS	VS Code (reStructuredText extension), PyCharm
Linux	VS Code (reStructuredText extension), vim, Sphinx (command line)
Web	FileFlip

RST questions people ask#

What is reStructuredText used for?

reStructuredText is the markup behind Python's own documentation and most Sphinx-built documentation sites, chosen because PEP 287 made it the standard format for Python docstrings. Its directive system lets a project define custom content types, which is why documentation with heavy cross-referencing tends to land on it over Markdown.

What's the difference between RST and Markdown?

reStructuredText defines directives and interpreted text roles as a formal extension mechanism, where Markdown relies on each implementation inventing its own extensions. RST is also more strictly specified, so a Docutils-conformant file parses the same way everywhere, at the cost of a more verbose syntax than Markdown's.

Can I convert RST to Markdown without losing anything?

Headings, paragraphs, lists and basic emphasis convert from reStructuredText to Markdown cleanly. Directives, most notably Sphinx-specific ones like toctree or code-block with language-aware highlighting, plus footnotes and substitution definitions, have no direct Markdown equivalent and either get dropped or flattened to plain text.

Converting RST files#

Every conversion runs inside your browser. The file is read from your disk, the work happens on your own machine, and nothing is uploaded. How FileFlip works names the engine behind each family and how to verify that for yourself.