HTML to reStructuredText Converter

About HTML to reStructuredText Converter

This tool converts HTML documents to reStructuredText (RST), the markup language used by Sphinx, Docutils, and the official Python documentation. It is perfect for turning existing HTML pages, help files, or API docs into RST for Read the Docs, Python packages, and technical manuals.

Key Features & Benefits

• Sphinx-ready output: Generates RST that works out of the box with Sphinx and Read the Docs.
• Flexible table support: Convert HTML tables into grid tables or simple tables depending on your documentation style.
• Preserved code blocks: HTML <pre><code> sections become RST .. code-block:: directives with optional language hints.
• Correct heading hierarchy: Maps HTML headings (h1–h6) to RST underline styles for clean table-of-contents generation.
• Accurate inline formatting: Bold, italics and inline code are kept as **bold**, *italic* and ``inline``.
• Links and images: Converts <a> and <img> elements into proper RST links and .. image:: directives.

How to Use the HTML to RST Tool

1. Paste or upload HTML: Provide HTML from documentation, a website, or an exported help file.
2. Choose options: Select grid vs simple tables, whether to include link anchors, and whether to preserve line breaks.
3. Preview the RST: The reStructuredText output updates automatically as you tweak options.
4. Copy or download: Copy the RST to your clipboard or download it as a .rst file ready for Sphinx.

Supported HTML Elements

• Headings: h1 (===), h2 (---), h3 (~~~), h4 (^^^), h5 ("""), h6 (''').
• Text formatting: strong/b → **bold**, em/i → *italic*.
• Code: code → ``inline``, pre → .. code-block::.
• Lists: ul → * bullets, ol → numbered lists.
• Links: a → `text <url>`_ (with optional anchors).
• Images: img → .. image:: with optional :alt:.
• Tables: table → grid or simple table syntax.
• Blockquotes: blockquote → indented quote blocks.
• Definition lists: dl/dt/dd → RST definition list structures.

Table Formats

Grid tables: Full-featured tables with borders (default)

+--------+-------+
| Header | Value |
+========+=======+
| Cell 1 | Data  |
+--------+-------+

Simple tables: Lightweight tables without borders

======= =====
Header  Value
======= =====
Cell 1  Data
======= =====

Example: HTML Section to reStructuredText

HTML input:

<h2>Installation</h2>
<p>Install the package using pip:</p>
<pre><code class="language-bash">pip install my-package</code></pre>

Generated RST:

Installation
------------

Install the package using pip:

.. code-block:: bash

   pip install my-package

Common Use Cases

• Sphinx documentation: Convert existing HTML docs to RST for Sphinx and Read the Docs.
• Python package docs: Migrate HTML-based docs into RST to follow Python ecosystem best practices.
• Technical manuals: Transform HTML help and knowledge base content into maintainable RST source files.
• API references: Turn HTML API docs into RST for automated cross-references and indexing.

RST Directives Used

The converter makes use of common reStructuredText directives:

• .. code-block:: For fenced code blocks with optional language identifiers.
• .. image:: For images, including :alt: text when available in the HTML.
• .. error:: For reporting parsing issues when the HTML cannot be converted cleanly.

Tips for High-Quality RST Output

• Start from clean HTML: Valid, semantic HTML produces the best reStructuredText.
• Pick the right table style: Use grid tables for complex tables and simple tables for short summary tables.
• Mark code blocks with languages: Use classes like language-python or language-bash so Sphinx can apply syntax highlighting.
• Review the result: Always skim the generated RST and adjust headings or tables where needed.

FAQ – HTML to reStructuredText Converter

• Is the generated RST compatible with Sphinx and Read the Docs?

  Yes. The output is standard reStructuredText that can be used directly in Sphinx documentation projects and hosted on Read the Docs.

• Can I edit the RST after conversion?

  Absolutely. The RST is meant as a starting point – you can edit it in any text editor, add Sphinx directives, or reorganize sections.

• Does the tool upload my HTML?

  No. All HTML to RST processing happens locally in your browser. Your documentation content is never sent to a server.

• What about very large HTML pages?

  For very long pages, consider converting sections separately. This keeps each RST file focused and easier to maintain within a Sphinx project.

Privacy & Security

All HTML to reStructuredText conversions run in your browser only. No HTML or RST data is transmitted externally, which is ideal for private documentation and internal developer guides.