md2bbcode

A wrapper and plugin for Mistune. It converts GitHub-flavored Markdown to Xenforo-flavored BBCode. Custom BBCodes made for RedGuides are included in bb_codes.xml.

Installation

You can install md2bbcode using pip:

pip install md2bbcode

Usage

After installation, you can use md2bbcode from the command line:

md2bbcode README.md

If the markdown includes relative images or other assets, you can use the --domain flag to prepend a domain to the relative URLs:

md2bbcode README.md --domain https://raw.githubusercontent.com/RedGuides/md2bbcode/main/

You can also use the package in your Python project:

from md2bbcode.main import process_readme

# Your Markdown content
markdown_text = "# Hell World"

# Optional domain to prepend to relative URLs
domain = 'https://raw.githubusercontent.com/yourusername/yourrepo/main/'

# Convert Markdown to BBCode
bbcode_output = process_readme(markdown_text, domain=domain)

# Output the BBCode
print(bbcode_output)

Debug Mode

You can use the --debug flag to save intermediate results to files for debugging:

md2bbcode README.md --debug

Development

If you want to contribute to md2bbcode or set up a development environment, follow these steps:

1. Clone the repository:

   git clone https://github.com/RedGuides/md2bbcode.git
   cd md2bbcode

2. Install Hatch, which is used for building and managing the project:

   pip install hatch

3. Create a development environment and install dependencies:

   hatch env create

4. Activate the development environment:

   hatch shell

renderers/bbcode.py

The custom plugin for Mistune, which converts AST to bbcode.¹

Additional Tools

html2bbcode

Converts several HTML tags typically allowed in Markdown to BBCode.²

html2bbcode input_file.html

md2ast

For debugging Mistune's renderer, converts a Markdown file to AST (JSON format).

md2ast input.md output.json

Features Test

Here are a few GitHub-flavored Markdown features so you can use this README.md for testing:

• Strikethrough: This text is struck through.

• Superscript: This text is normal and this is ^superscript.

• Table:

  Syntax	Description
  Header	Title
  Paragraph	Text

Todo

• refactor html2bbcode
• update for new Xenforo 2.3 and 2.4 BBCode

Footnotes

1. Mistune does not convert Markdown HTML to AST, hence the need for html2bbcode. ↩

2. Currently used for post-processing mistune output, but there's a better way. See inside the file for a suggestion. ↩