RST to HTML
Nothing you choose here leaves your browser, and nothing is downloaded to make it work. You can paste instead of choosing a file.
A complete page out of the markup Sphinx and Python's documentation use.
Sections, lists, literal blocks, block quotes, links, images and the directives people actually use — code-block, image, figure, note and its relatives. The interesting part is the headings, and it has its own section below because getting it wrong turns a document inside out.
A heading's level is not decided by its underline
=== is not “heading 1”.
reStructuredText has no fixed hierarchy at all: the level
of a section is decided by the order in which its underline character
first appears in the document. A file that underlines its top-level
sections with - and its subsections with = is
perfectly correct RST, and is not unusual — several large projects
write it that way.
A converter with a table mapping = to h1 turns
such a document inside out: every section becomes a subsection of its own
subsection. This remembers the characters in the order it meets them and
uses the position in that list, which is the actual rule. The check for it
uses a document with the characters the other way round and compares
against docutils by way of pandoc, because a test written
in the conventional order would pass with the broken version and prove
nothing.
The other two that are easy to get wrong
A paragraph ending in :: announces a literal
block, and the :: is not text. After a word
it leaves a single colon — “as follows::” reads
“as follows:” — and alone on its line it disappears
entirely. Print it and you get a document littered with stray double
colons, which is what a surprising number of converters do.
And .. thing:: is a
directive while .. thing is a
comment. One colon apart. A converter that treats them
alike either prints every comment into your document or silently drops
every image.
What is read, and what is not
Read: sections, paragraphs, bullet and enumerated lists to
any depth, literal blocks, block quotes, transitions, field lists, inline
emphasis, strong and literals, links both inline and named, images, and the
directives people actually use — code-block,
code, image, figure,
note, warning, tip and
important.
Not read: tables, in either of RST's two
syntaxes, so a table's text arrives as paragraphs. Nor footnotes,
citations, substitutions or include. Roles such as
:ref:`name` keep their text and lose the link. A directive
this does not know keeps the words inside it and reports that it
did, because those words are usually yours.
Where to go next
- RST to Markdown — another way through
- Markdown to RST — another way through
- HTML to RST — the other way round