` | `AST::Align` | ### Lists | Tags | Renders as | AST node | | --------------------------- | ---------- | --------------- | | `[list]`, `[ul]`, `[ulist]` | `- item` | `AST::List` | | `[ol]`, `[olist]` | `1. item` | `AST::List` | | `[*]`, `[li]`, `[.]` | List item | `AST::ListItem` | ### Tables | Tags | Renders as | AST node | | --------------------------------- | ---------- | ------------ | | `[table]`, `[tr]`, `[td]`, `[th]` | GFM table | `AST::Table` | ### Self-closing | Tags | Renders as | AST node | | ------ | --------------- | --------------------- | | `[br]` | Hard line break | `AST::LineBreak` | | `[hr]` | `---` | `AST::HorizontalRule` | A few tags take variants: * **Code language** — `[code=ruby]` or `[code lang=ruby]`. * **Ordered list** — `[list=1]` (same as `[ol]`). * **Quote attribution** — `[quote="author, post:1, topic:2"]`. * **Link forms** — `[url]` also accepts `[url=href]text[/url]` and `[url]href[/url]`; `[email=addr]text[/email]` and `[img=src]alt[/img]` follow the same shape. * **Bare links** — a `[url]` whose text equals the href (or has no text) renders as the plain link, not `[href](href)`, so Discourse autolinks and oneboxes it. For the exact registration list, see [`HandlerRegistry.default`](https://github.com/discourse/markbridge/blob/main/lib/markbridge/parsers/bbcode/handler_registry.rb). ## Using the parser directly The `bbcode_to_markdown` convenience wraps parser + renderer. Calling them directly gives you the AST for inspection or custom rendering: ```ruby parser = Markbridge::Parsers::BBCode::Parser.new ast = parser.parse("[b]bold[/b] with [unknown]mystery[/unknown]") parser.unknown_tags # => {"unknown" => 2} # count of open + close tokens seen renderer = Markbridge::Renderers::Discourse::Renderer.new renderer.render(ast) # => "**bold** with mystery" ``` For most callers, `parse_bbcode` is the better entry point — it returns a `Parse` object that already exposes `.unknown_tags` and `.diagnostics` without reaching for the parser instance. ## Closing strategies BBCode inputs from real forums often have mismatched or out-of-order tags. Markbridge ships with two strategies: * **Reordering** (default) — reconciles sequences of up to 5 mismatched closing tags, e.g. `[b][i]text[/b][/i]` → `Bold(Italic("text"))`. * **Strict** — only auto-closes; won’t reorder. More predictable, more likely to reject input. ```ruby require "markbridge/bbcode" handlers = Markbridge::Parsers::BBCode::HandlerRegistry.build_from_default do |registry| reconciler = Markbridge::Parsers::BBCode::ClosingStrategies::TagReconciler.new(registry:) registry.closing_strategy = Markbridge::Parsers::BBCode::ClosingStrategies::Strict.new(reconciler) end Markbridge.bbcode_to_markdown("[b][i]text[/b][/i]", handlers:) ``` ## Graceful degradation Unknown tags don’t raise. The wrapper is skipped; children are parsed normally: ```ruby Markbridge.bbcode_to_markdown("[unknown]inner text[/unknown]") # => "inner text" ``` Unknown tag counts are surfaced on `Conversion#unknown_tags` (and `Parse#unknown_tags`) — no need to drop to the parser instance. ## Limits * **Max nesting depth**: 100. Exceeding raises `MaxDepthExceededError`. * **Max auto-close depth**: 5 levels — also bounds how deep `Reordering` will look for a matching opener. ## Customizing Register a custom handler to recognize a new tag, or replace the built-in one: ```ruby handlers = Markbridge::Parsers::BBCode::HandlerRegistry.build_from_default do |registry| registry.register("callout", MyCalloutHandler.new) end Markbridge.bbcode_to_markdown(input, handlers:) ``` See [Extending Markbridge](/customization/extending/) for a full walkthrough, or [Wrapping a default handler](/customization/extending/#wrapping-a-default-handler) for `HandlerRegistry#overlay` — the cleanest way to delegate to the default for the cases your handler doesn’t need to change. # HTML > Convert HTML into Discourse-flavored Markdown using Nokogiri. The HTML parser uses Nokogiri to tolerate malformed HTML and produces the same AST the other parsers feed into. ## Requirements Add `nokogiri` to your Gemfile. It’s a runtime dependency for the HTML parser: ```ruby gem "nokogiri" ``` ## Quick start ```ruby require "markbridge/html" result = Markbridge.html_to_markdown("

Hello world!

") result.markdown # => "Hello **world**!" ``` `result` is a [`Markbridge::Conversion`](/concepts/result-objects/) — `.markdown`, plus `.unknown_tags`, `.errors` for migration use. To get the AST: ```ruby parse = Markbridge.parse_html("link") parse.ast # => AST::Document(Url("link", href: "https://example.com")) ``` ## Supported tags | HTML | Renders as | AST node | | --------------------------------- | ------------------------------------------------ | ------------------------------------ | | ``, `` | `**bold**` | `AST::Bold` | | ``, `` | `*italic*` | `AST::Italic` | | ``, ``, `` | `~~strike~~` | `AST::Strikethrough` | | `` | `underline` | `AST::Underline` | | `^{`, `_{` | `^…` / `_…` | `AST::Superscript`, `AST::Subscript` |
| ``, `` | Code span; fenced block for multiline content | `AST::Code` |
| `` | Fenced code block, including single-line content | `AST::Code` |
| ``–`
` | `#` through `######` headings | `AST::Heading` |
| `` | `[text](href)` | `AST::Url` |
| `` | `![](src)` | `AST::Image` |
| `` | `[quote]…[/quote]` | `AST::Quote` |
| ``, `` | `- item` / `1. item` | `AST::List` |
| `` | List item | `AST::ListItem` |
| ``, ``, ``, ``, `` are transparent — their children are processed as if the wrapper weren’t there. Unregistered tags are skipped, but their children are still processed (graceful degradation).

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

## Code languages

For syntax highlighting, the parser uses the first valid language from:

1. A `language-*` class on the element.
2. A `language-*` class on its direct `` child.
3. The element’s `lang` attribute.
4. A single class on the element or its direct `` child.

The language must contain only letters, digits, underscores, plus signs, or hyphens, and start with a letter or digit. A class list such as `hljs codeblock` does not become a language.

````ruby
require "markbridge/html"

result = Markbridge.html_to_markdown('puts 1')
result.markdown
# => "```ruby\nputs 1\n```"
````

## Parser characteristics

* **Uses Nokogiri’s HTML fragment parser** — handles malformed input without raising.
* **Stateless handlers** — simpler than BBCode’s open/close callback API. A handler is an object responding to `#process(element:, parent:)`.

```ruby
class AsideHandler < Markbridge::Parsers::HTML::Handlers::BaseHandler
def initialize
@element_class = AST::Quote
end

attr_reader :element_class

def process(element:, parent:)
note = AST::Quote.new
parent << note
note # return node to recurse into for children
end
end

handlers =
Markbridge::Parsers::HTML::HandlerRegistry.build_from_default do |registry|
registry.register("aside", AsideHandler.new)
end

Markbridge.html_to_markdown("heads up", handlers:)
```

## Using the parser directly

```ruby
parser = Markbridge::Parsers::HTML::Parser.new
ast = parser.parse("rich content")

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

## What’s not supported

The default registry is intentionally scoped to the Discourse-facing subset. Notably:

* Inline styles and ``/`` without handlers pass through transparently (children only).
* ``, ` ` | GFM table | `AST::Table` |
| `
` | Hard line break | `AST::LineBreak` |
| `` | `---` | `AST::HorizontalRule` |
| `` | Paragraph spacing | — (transparent) |

`}}