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 (derogatory).

Installation

Install as a CLI tool with pipx:

pipx install md2bbcode

Usage

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

md2bbcode README.md

Output prints to stdout as UTF-8. To write straight to a file (recommended on Windows, where shell > redirection can mangle the encoding), use -o:

md2bbcode README.md -o output.bbcode

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 import process_readme

bbcode = process_readme("# Hell World")
print(bbcode)

Pass a domain to rewrite relative URLs (e.g. images and links in a repo README) to absolute ones:

bbcode = process_readme(
    markdown_text,
    domain="https://raw.githubusercontent.com/yourusername/yourrepo/main/",
)

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 ↩