reStructuredText to HTML Converter

How it works

reStructuredText is the documentation language of the Python world: the README.rst of a PyPI package, documentation written with Sphinx and the CHANGELOG of many open-source projects use it. When you want to see such a file outside GitHub, or move its content into a web page, paste the text here. For example, the "Installation" heading in your package's README.rst, its numbered steps, the pip command introduced by :: and the options table come out on the right as h2, ol, pre and table elements; a .. note:: block becomes a div with the title "Note". Heading levels follow the docutils rule: the level is given by the order in which each underline character first appears, so if you used = before -, = is level one and - is level two. Supported structures: headings with underline or overline, paragraphs, bullet and numbered lists (nested), definition and field lists, line blocks, block quotes, transitions, literal and doctest blocks, simple and grid tables, the image, figure, code-block and admonition directives, and links resolved through .. _name: targets. Sphinx-specific directives such as toctree, contents and include are skipped and counted in the result line rather than swallowed silently. The output is HTML source: choose "Body" to embed it in a page and "Full page" to open it as a file.

This tool is also known as rst to html, rst to html converter, restructuredtext to html, convert rst to html online, rst file viewer, readme.rst preview.

What is reStructuredText (RST)?

reStructuredText is the plain-text markup language the Python community has used since 2002; its file extension is .rst. A heading is written with a line of ===== or ----- underneath it, emphasis with *asterisks*, code with ``double backticks`` and a link with the `text <address>`_ pattern. What sets it apart from Markdown are directives: blocks such as .. note::, .. image:: and .. code-block:: give the document an extensible structure. The README.rst files of PyPI packages, documentation sites generated with Sphinx and Python's own documentation are written in it; the standard converter is docutils.

What is HTML?

HTML is the page language a browser understands: it marks the structure of content with tags such as <h1> for a heading, <p> for a paragraph, <ul> for a list and <table> for a table. This tool turns every RST structure into the HTML tag with the same meaning; admonitions and code blocks receive class names so a stylesheet can be attached. The output has no appearance (CSS) of its own, only structure — pasted into a blog post or a content management system it takes on that page's style automatically. Raw HTML and javascript: addresses are deliberately not passed through.

What is the difference between RST and Markdown?

Both format plain text, but they belong to different worlds. Markdown is short and loose: # heading, **bold**, [link](address); GitHub, forums and note apps use it, it has many dialects, and tables or admonition boxes are not part of the standard. reStructuredText is stricter and richer: headings are underlined, directives (.. note::, .. code-block::) and roles (:sup:, :ref:) make the document extensible, and tables and footnotes are part of the standard — which is why Python documentation and Sphinx prefer it. One can be converted to the other automatically, but not one to one: most Markdown structures have an RST counterpart, while RST directives have none in Markdown.

Which directives are converted and which are skipped

The strength of RST is its directives (blocks starting with .. name::), and some of them only mean something inside Sphinx. This tool converts the directives that produce document content: image and figure become image elements, code-block / code / sourcecode become a code block with a language class, and note / warning / tip / important / caution / danger / hint / attention / error become an admonition box whose title is written in the page language.

Directives that belong to the build process rather than to the document — toctree, contents, include, math, csv-table, list-table — produce no HTML; their bodies do not leak into the output and the result line counts them as "N unsupported directives skipped", so you know a section is missing without scanning the output. .. raw:: html is deliberately unsupported: no raw HTML can be injected into a page through RST input.

Why the output does not 'look' like a page

What you see in the right panel is HTML source, not a rendered page — the tags are written out. That is intentional: the tool's job is to make the text portable. To see the result, choose "Full page", download the .html file and double-click it; the browser opens it like any page.

The output carries no styling (CSS); admonitions are marked with the admonition class and code blocks with classes such as language-python, so you can attach your own stylesheet. In links, only http(s), mailto, tel and relative addresses are kept; javascript: and data: addresses are replaced with #.

• Body HTML → pasting into a blog post, a CMS editor or an existing page
• Full page → saving as a file and opening it in the browser, attaching to an e-mail
• If your source is Markdown → use the separate Markdown to HTML tool; the two syntaxes do not mix

Frequently asked questions

How do I convert an RST file to HTML?

Open the .rst file in a text editor, copy its content and paste it into the left panel; the HTML is produced on the right immediately. To save it as a file, choose "Full page" and tap Download. The text never leaves your device; the conversion runs inside the browser.

Why are Sphinx directives such as toctree or autodoc missing from the output?

They are not document content but placeholders that Sphinx fills from other files at build time; they cannot be produced from a single text. The tool skips them and the result line says how many directives were skipped. Content directives — headings, lists, tables, code blocks and admonitions — are converted in full.

Why did the heading levels come out differently than I expected?

In RST no character is tied to a fixed level; like docutils, this tool assigns levels in the order in which each underline style first appears in the document. A heading with an overline counts as a different style from the same character used as underline only. If the document starts with = and then uses -, you get h1 and h2 in that order.

What happens if I paste Markdown?

Markdown's # headings and [text](address) links are not RST syntax; they come out as plain paragraphs and the result line reports that no structure was found. Use the separate Markdown to HTML tool for Markdown. The easy way to recognise RST: the ===== or ----- lines under headings and the directive lines starting with ..