Skip to content

README.md

Latest commit

 

History

History
136 lines (92 loc) · 4.08 KB

README.md

File metadata and controls

136 lines (92 loc) · 4.08 KB
Raw

Publish to PyPI

md2bbcode logo, original image 'A Specious Origin' by Jerry LoFaro.

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.1

Additional Tools

html2bbcode

Converts most HTML tags typically allowed in Github Flavored Markdown to BBCode.2

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 H2O.

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 ↩