<SYSTEM>TextFormatter: Source version: Markbridge 0.4.2. These docs are built from the repository and may include unreleased changes.</SYSTEM>

# TextFormatter

> Convert s9e/TextFormatter XML (used by phpBB 3.2+) into Discourse-flavored Markdown.

The TextFormatter parser reads the XML format produced by [s9e/TextFormatter](https://github.com/s9e/TextFormatter), the library phpBB 3.2+ uses to store parsed BBCode. Converting the stored XML directly is faster and more faithful than re-parsing the original BBCode.

## Requirements

Add `nokogiri` to your Gemfile. It’s a runtime dependency for the TextFormatter parser:

```ruby
gem "nokogiri"
```

## Quick start

```ruby
require "markbridge/textformatter"


xml = "<r><B><s>[b]</s>Hello<e>[/b]</e></B> world!</r>"
result = Markbridge.text_formatter_xml_to_markdown(xml)
result.markdown
# => "**Hello** world!"
```

## The s9e format in brief

TextFormatter wraps content in one of two roots:

* `<t>` — plain text (no BBCode was used).
* `<r>` — rich text (contains formatted elements).

Inside `<r>`, formatted children use **uppercase element names** by convention (`<B>`, `<URL>`, `<CODE>`). Each formatted element may wrap its original BBCode markup in `<s>` (start) and `<e>` (end) tags — Markbridge ignores these during parsing.

## Supported elements

| Element                   | Renders as                                       | AST node              |
| ------------------------- | ------------------------------------------------ | --------------------- |
| `<B>`                     | `**bold**`                                       | `AST::Bold`           |
| `<I>`                     | `*italic*`                                       | `AST::Italic`         |
| `<S>`                     | `~~strike~~`                                     | `AST::Strikethrough`  |
| `<U>`                     | `<u>underline</u>`                               | `AST::Underline`      |
| `<CODE>`                  | Fenced code block, including single-line content | `AST::Code`           |
| `<URL>`                   | `[text](href)`                                   | `AST::Url`            |
| `<EMAIL>`                 | `[text](mailto:addr)`                            | `AST::Url`            |
| `<IMG>`                   | `![](src)`                                       | `AST::Image`          |
| `<ATTACHMENT>`            | Discourse upload syntax                          | `AST::Attachment`     |
| `<QUOTE>`                 | `[quote]…[/quote]`                               | `AST::Quote`          |
| `<LIST>`                  | `- item` / `1. item`                             | `AST::List`           |
| `<LI>`                    | List item                                        | `AST::ListItem`       |
| `<TABLE>`, `<TR>`, `<TD>` | GFM table                                        | `AST::Table`          |
| `<HR>`                    | `---`                                            | `AST::HorizontalRule` |
| `<br/>`                   | Hard line break                                  | `AST::LineBreak`      |

Several elements carry attributes Markbridge reads: `<CODE>` (`lang`), `<URL>` (`url`), `<EMAIL>` (`email`), `<IMG>` (`src`), `<LIST>` (`type` — `bullet` or `decimal`), and `<QUOTE>` (attribution).

For the exact list, see [`HandlerRegistry.default`](https://github.com/discourse/markbridge/blob/main/lib/markbridge/parsers/text_formatter/handler_registry.rb).

## Using the parser directly

```ruby
parser = Markbridge::Parsers::TextFormatter::Parser.new
ast = parser.parse(xml)


renderer = Markbridge::Renderers::Discourse::Renderer.new
renderer.render(ast)
```

## Behavior notes

* **Invalid XML** falls back to treating the input as plain text instead of raising.
* **Unknown elements** are skipped — their children are still processed.
* **Stateless handler API**: like the HTML parser, handlers are callables receiving `(element:, parent:, processor:)`. The `processor:` argument is the parser instance and exposes `process_children(xml_element, ast_node)` for handlers that want to recurse manually. Lambdas are accepted.

## When to use this vs. the BBCode parser

If you’re migrating **from** phpBB 3.2+ and already have the stored XML, use this parser — it’s both faster and closer to the source of truth than re-parsing the BBCode. For plain BBCode from other forums, use the [BBCode parser](/format-guides/bbcode/).