md2bbcode

A wrapper and plugin for Mistune. It converts most GitHub-flavored Markdown to Xenforo-flavored BBCode.

Tip

Custom BBCodes made for RedGuides are included in bb_codes.xml, import the ones you want in your Xenforo installation at admin.php?bb-codes. Some custom BBCodes include css, which you can split off to your extra.css template for more efficiency.

Note

This project is made with LLM assistance.

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. Create a development environment and install dependencies:

   hatch env create
   

3. Activate the development environment:

   hatch shell
   

renderers/bbcode.py

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

Additional Tools

html2bbcode

Converts most HTML tags typically allowed in Github Flavored 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, including the table:

Feature	Markdown	Rendered
Bold	**text**	bold
Italic	*text*	italic
Strikethrough	~~text~~	struck
Code	`code`	inline
Link	[text](url)	example
Superscript	<sup>2</sup>	E=mc2
Subscript	<sub>2</sub>	H2O

HTML spoiler (details/summary)

html2bbcode test. This is hidden content. Water is H₂O.

Font tag inside details size 3 Arial red

Inline style inside details green times new roman strikethrough italic bold underline

This is a quote by John Doe

Footnotes

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

2. Currently used for post-processing mistune output. Reference: https://github.github.com/gfm/#raw-html ↩