Get started: Source version: Markbridge 0.4.2. These docs are built from the repository and may include unreleased changes. # Get started > Install Markbridge, convert your first document, and read the result. Install Markbridge, choose the parser for your input, and read the converted Markdown. See the [Introduction](/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`: ```bash bundle add markbridge ``` Or install it directly: ```bash gem install markbridge ``` ## Your first conversion ```ruby 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: ```bash 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](/concepts/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](/format-guides/bbcode/) | | `Markbridge.html_to_markdown` | HTML (via Nokogiri) | [HTML](/format-guides/html/) | | `Markbridge.mediawiki_to_markdown` | MediaWiki wikitext | [MediaWiki](/format-guides/mediawiki/) | | `Markbridge.text_formatter_xml_to_markdown` | s9e/TextFormatter XML (phpBB 3.2+) | [TextFormatter](/format-guides/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: ```ruby RENDERER = Markbridge.discourse_renderer(escape_hard_line_breaks: true) result = Markbridge.bbcode_to_markdown("hi \nthere", renderer: RENDERER) ``` See [Customizing the renderer](/customization/customizing-renderer/) for all options (custom tags, dropping tags, custom escaper, postprocessor). ## Next steps * **Converting your format?** See the [format guides](/format-guides/) for full tag coverage. * **Customizing the output?** See [Customizing the renderer](/customization/customizing-renderer/). * **Adding a tag the parser doesn’t know?** See [Extending Markbridge](/customization/extending/). * **Migrating a forum?** Start with [Migrating to Discourse](/migrating/overview/). # Introduction > What Markbridge is, how it works, and where to go from here. Markbridge is a Ruby library that converts **BBCode, HTML, MediaWiki wikitext, and s9e/TextFormatter XML** into Discourse-flavored Markdown. You can convert individual documents or process a large collection. You can also inspect the parsed content and customize the output.  1. **Parse** — a format-specific parser reads your input and builds an `AST::Document`. You can review unknown tags in the result. 2. **AST** — a renderer-agnostic tree. The same shape comes out no matter which format went in. 3. **Render** — the Discourse renderer walks the tree and emits Markdown. The parse and AST stages know nothing about Discourse — “Discourse-flavored” is just what the shipped renderer produces. You could point a different renderer at the same AST. ## Four input formats, one renderer Markbridge ships four parsers that all feed the same Discourse renderer: [BBCode](/format-guides/bbcode/), [HTML](/format-guides/html/), [MediaWiki](/format-guides/mediawiki/), and [s9e/TextFormatter XML](/format-guides/textformatter/). Pick the one that matches your source — [Getting Started](/getting-started/) shows the exact method for each. ## When to use it Use Markbridge when you need to convert existing markup to Markdown, inspect structured content, or adapt output to your application. **Forum migration to Discourse** is the main use case. You can track unknown tags, handle conversion errors per post, and use custom AST nodes for references to uploads, users, and topics. The [migration guide](/migrating/overview/) explains that workflow. ## Find your way around * **[Getting Started](/getting-started/)** — install and run your first conversion. * **[Format guides](/format-guides/)** — exactly how each input maps to Markdown. * **[Customization](/customization/)** — build a reusable renderer, and add your own tags and handlers. * **[Concepts](/concepts/)** — the architecture, the AST, the parsers and renderer, and performance. * **[Migrating to Discourse](/migrating/overview/)** — the full forum-migration workflow.