Convert BBCode to RST

Why Convert BBCode to RST?

Converting BBCode to reStructuredText (RST) is valuable when you need to migrate forum-based content into professional documentation systems. RST is the standard documentation format for Python projects and Sphinx, making this conversion essential when technical discussions, tutorials, or guides originally posted on forums need to be incorporated into official project documentation or published on platforms like Read the Docs.

BBCode's square bracket tags map naturally to RST's inline markup conventions. Bold text ([b]...[/b]) becomes **bold**, italic ([i]...[/i]) becomes *italic*, and code blocks ([code]...[/code]) are converted to RST's code-block directives with proper indentation. Links, images, and lists are similarly translated, preserving the original content's structure while adopting RST's more powerful documentation-oriented syntax.

RST offers significant advantages over BBCode for documentation purposes. Its directive system supports admonitions (notes, warnings, tips), table of contents generation, cross-references between documents, mathematical notation, and syntax-highlighted code blocks for dozens of programming languages. By converting BBCode to RST, you unlock these capabilities and gain access to Sphinx's extensive ecosystem of themes, extensions, and output formats including HTML, PDF, ePub, and man pages.

This conversion is particularly useful for open-source projects where community knowledge accumulated in forum discussions needs to be formalized as documentation. Developer guides, FAQ sections, and troubleshooting tips from forums can be converted to RST and integrated into a Sphinx documentation tree, creating a unified and searchable knowledge base that serves both new and experienced users.

Key Benefits of Converting BBCode to RST:

• Professional Documentation: Transform forum content into Sphinx-ready documentation
• Python Standard: Use the official documentation format for Python projects
• Cross-References: Add inter-document linking and references
• Code Highlighting: Syntax highlighting for all major programming languages
• Multiple Outputs: Generate HTML, PDF, ePub, and more from a single source
• Read the Docs: Host documentation on Read the Docs platform
• Extensible: Access Sphinx's rich extension ecosystem

Practical Examples

Example 1: Forum Tutorial to Documentation

Input BBCode file (tutorial.bbcode):

[b]Getting Started Guide[/b]

[i]This tutorial covers the basics.[/i]

[b]Installation[/b]
[code]pip install mypackage[/code]

[b]Usage[/b]
[list]
[*]Import the module
[*]Create an instance
[*]Call the run method
[/list]

Output RST file (tutorial.rst):

Getting Started Guide
=====================

*This tutorial covers the basics.*

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

.. code-block:: bash

   pip install mypackage

Usage
-----

* Import the module
* Create an instance
* Call the run method

Example 2: Forum Post with Links and Quotes

Input BBCode file (discussion.bbcode):

[b]API Reference Notes[/b]

[quote]The API supports RESTful endpoints
for all CRUD operations.[/quote]

See the docs: [url=https://api.example.com]API Docs[/url]

[b]Important:[/b] Always authenticate first.

Output RST file (discussion.rst):

API Reference Notes
===================

   The API supports RESTful endpoints
   for all CRUD operations.

See the docs: `API Docs <https://api.example.com>`_

.. important::

   Always authenticate first.

Example 3: Forum FAQ to Documentation Page

Input BBCode file (faq.bbcode):

[b]Frequently Asked Questions[/b]

[b]Q: How do I install?[/b]
Run [code]pip install mylib[/code] in your terminal.

[b]Q: What Python versions are supported?[/b]
Python 3.8 and above are supported.

[b]Q: Where do I report bugs?[/b]
Use our [url=https://github.com/example/issues]issue tracker[/url].

Output RST file (faq.rst):

Frequently Asked Questions
=========================

How do I install?
-----------------

Run ``pip install mylib`` in your terminal.

What Python versions are supported?
------------------------------------

Python 3.8 and above are supported.

Where do I report bugs?
-----------------------

Use our `issue tracker <https://github.com/example/issues>`_.

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText is a lightweight markup language designed for technical documentation. It is part of the Python Docutils project and serves as the standard documentation format for Python. RST uses punctuation characters for formatting (asterisks for emphasis, backticks for code, underlines for headings) and provides powerful directives for structured content like code blocks, admonitions, tables, and cross-references.

Q: How are BBCode formatting tags mapped to RST?

A: BBCode tags are converted to their RST equivalents: [b] becomes ** (strong), [i] becomes * (emphasis), [code] becomes double backticks or code-block directives, [url] becomes RST hyperlink references, [quote] becomes indented block quotes, and [list] items become RST bullet lists with asterisks. Headings are created with underline characters matching the title length.

Q: Can I use the converted RST with Sphinx?

A: Yes! The converted RST files are fully compatible with Sphinx. You can add them to your Sphinx project's source directory, include them in your toctree directive, and build professional documentation in HTML, PDF, or ePub format. Sphinx will process the RST markup, generate cross-references, build search indexes, and apply your chosen theme.

Q: Does RST support syntax highlighting?

A: Yes! RST with Sphinx supports syntax highlighting for over 300 programming languages via the Pygments library. BBCode [code] blocks are converted to RST code-block directives where you can specify the language. For example, a Python code block uses the directive .. code-block:: python followed by indented code, producing beautifully highlighted output in any format.

Q: How does RST handle images from BBCode?

A: BBCode [img] tags are converted to RST image directives. The RST image directive (.. image:: url) supports additional options like width, height, alt text, alignment, and scaling that are not available in BBCode. The converter preserves the image URL and creates a properly formatted RST image directive that can be further customized.

Q: Is RST better than Markdown for documentation?

A: RST is more powerful than Markdown for technical documentation due to its directive system, cross-referencing capabilities, and tight Sphinx integration. RST supports admonitions, footnotes, table of contents generation, and extensible roles. Markdown is simpler and more widely known, but RST provides the structured features needed for large documentation projects, especially in the Python ecosystem.

Q: Can RST files be rendered on GitHub?

A: Yes, GitHub natively renders RST files. When you push .rst files to a GitHub repository, they are automatically rendered as formatted HTML in the web interface. This includes headings, bold/italic text, code blocks, lists, links, and images. However, some advanced Sphinx-specific directives may not render correctly on GitHub since they require Sphinx processing.

Q: What happens to BBCode color and size tags in RST?

A: RST does not have native support for text colors or arbitrary font sizes. BBCode [color] and [size] tags are stripped during conversion, preserving only the text content. If you need colored or specially sized text in RST output, you can use custom roles or raw HTML directives, but this is generally discouraged in favor of semantic markup like admonitions and emphasis.