md2bbcode

Converts most GitHub-flavored Markdown and HTML to XenForo-flavored BB code. It uses Mistune. You can also configure it to work with your favorite ancient community.

Installation

pipx install md2bbcode

Usage

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

Relative paths

Use --domain to turn relative links and image paths, such as guide.md and images/logo.png, into full URLs:

md2bbcode README.md --domain https://example.com/docs/

For GitHub, use the repo URL. This assumes you use the default branch:

md2bbcode README.md --domain https://github.com/RedGuides/md2bbcode

md2bbcode README.md --link-base https://github.com/RedGuides/md2bbcode/blob/main/ --image-base https://raw.githubusercontent.com/RedGuides/md2bbcode/main/

Your board's custom BB codes

XenForo has no built-in tag for highlights, superscript, subscript, abbreviations, anchors, and others, so md2bbcode writes those with custom BB codes. By default it assumes your board has the RedGuides set of custom BB codes.

If your board has its own custom BB codes, export them at admin.php?bb-codes in XenForo and use them:

md2bbcode README.md --bb-codes bb_codes.xml

md2bbcode checks the HTML each BB code produces to find the right tag for your board. For example, if [highlight] produces <mark>{text}</mark>, then ==text== becomes [HIGHLIGHT]text[/HIGHLIGHT].

If your board has no matching BB code, md2bbcode uses a simpler alternative, such as plain text, inline code, or a quote.

Use --no-custom-bbcode if your board has only default XenForo BB code.

Changing a tag

Put the settings you want to change in a TOML file, such as myboard.toml. This example changes inline code to [CODE] and turns off highlighting:

[tags]
codespan = "[CODE]{text}[/CODE]"
mark = "{text}"

{text} keeps the content. Using it alone removes the surrounding tag, so ==highlighted text== becomes plain text. These settings apply to HTML in your Markdown too.

Apply your config with --config:

md2bbcode README.md --config myboard.toml

To find other tag names and see their current settings, use --dump-config:

md2bbcode --dump-config

unknown_html = "strip"

bb_codes = "bb_codes.xml"

HTML files

md2bbcode also installs html2bbcode, which converts an HTML file the same way md2bbcode converts the HTML inside Markdown. It takes the same -o, --domain, --config and --bb-codes options:

html2bbcode page.html -o output.bbcode

Use in Python

from md2bbcode import convert

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

Use domain for relative links and images, with the same automatic GitHub handling as the CLI:

bbcode = convert(
    markdown_text,
    domain="https://github.com/yourusername/yourrepo",
)

from md2bbcode import Dialect, convert

bbcode = convert(markdown_text, dialect=Dialect.load("myboard.toml"))

bbcode = convert(markdown_text, dialect=Dialect.defaults(bb_codes="bb_codes.xml"))

Development

You need Hatch, which you can install with pipx install hatch. Then clone the repository and run the tests:

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

hatch test -- --update-goldens

md2bbcode README.md --ast