Get started

Install Markbridge, choose the parser for your input, and read the converted Markdown. See the Introduction for an overview of the library.

Requirements

You need Ruby 3.3 or newer. Markbridge supports CRuby, JRuby, and TruffleRuby.

Install

Add to your Gemfile:

bundle add markbridge

Or install it directly:

gem install markbridge

Your first conversion

require "markbridge/bbcode"

bbcode = "[b]Hello[/b] [url=https://example.com]world[/url]!"
result = Markbridge.bbcode_to_markdown(bbcode)
puts result.markdown
# => **Hello** [world](https://example.com)!

require "markbridge/bbcode" loads the BBCode parser plus the Discourse renderer. Swap bbcode for html, mediawiki, or textformatter for the other formats, or use markbridge/all to load all four at once. For HTML or TextFormatter, also add Nokogiri to your bundle:

bundle add nokogiri

BBCode and MediaWiki do not need Nokogiri.

*_to_markdown returns a Markbridge::Conversion value object, not a plain string. The rendered Markdown is on .markdown; .to_s delegates to it so puts result and string interpolation "#{result}" work. The Conversion also carries .unknown_tags, .diagnostics, and .errors — see Result objects for the full shape.

The four formats

Pick the method that matches your input:

Method	Input format	Guide
Markbridge.bbcode_to_markdown	BBCode like [b]...[/b]	BBCode
Markbridge.html_to_markdown	HTML (via Nokogiri)	HTML
Markbridge.mediawiki_to_markdown	MediaWiki wikitext	MediaWiki
Markbridge.text_formatter_xml_to_markdown	s9e/TextFormatter XML (phpBB 3.2+)	TextFormatter

Markbridge.convert(input, format: :bbcode) dispatches to the right one when the format isn’t fixed at the call site (useful when your application accepts several formats).

Each *_to_markdown method has a matching parse_* method that returns a Parse (with the AST and unknown-tag data) instead of rendering — useful when you want to inspect, transform, or re-render with a custom renderer.

Customizing output

Output is controlled by a Renderer instance, built once via Markbridge.discourse_renderer(...) and reused across calls:

RENDERER = Markbridge.discourse_renderer(escape_hard_line_breaks: true)

result = Markbridge.bbcode_to_markdown("hi   \nthere", renderer: RENDERER)

See Customizing the renderer for all options (custom tags, dropping tags, custom escaper, postprocessor).

Next steps

• Converting your format? See the format guides for full tag coverage.
• Customizing the output? See Customizing the renderer.
• Adding a tag the parser doesn’t know? See Extending Markbridge.
• Migrating a forum? Start with Migrating to Discourse.