Convert BBCode to Markdown

What is BBCode?

BBCode — short for Bulletin Board Code — is a lightweight markup language that became the dominant formatting system for online forums in the late 1990s and 2000s. It was introduced by the Ultimate Bulletin Board software in 1998 as a safer alternative to raw HTML: users could style their posts (bold, italic, links, quotes, code blocks) using square-bracketed tags instead of HTML, which the forum software would server-side translate into sanitized HTML. The syntax — [b]bold[/b], [url=link]text[/url], [quote]...[/quote] — became ubiquitous on phpBB, vBulletin, SMF, MyBB, Invision Power Board, and dozens of other forum platforms.

BBCode's relevance peaked in the 2000–2015 era when forum-based communities were the default internet gathering place. Gaming communities, hobby forums, programming help boards, regional communities — all ran on BBCode-powered software. A generation of internet users learned to format text by typing square brackets. The format's decline mirrors the broader shift from forums to social media platforms, Discord, Slack, and subreddit-style aggregators. But BBCode content still exists in volume: decade-plus-old forum archives, specialty communities that never migrated (amateur radio, model railroading, competitive gaming tactical guides), and threads with real reference value that survive in search indexes.

Most BBCode-to-Markdown migrations today are archive rescues. A forum is shutting down, or a community is moving to Discourse / Obsidian / a static documentation site, and the old content needs to come with them in a readable format.

Why migrate to Markdown?

Modern communities have largely standardized on Markdown. Discord supports Markdown. Slack accepts most of it. Reddit renders its own dialect. Discourse (the modern open-source forum platform) uses Markdown as its primary format with BBCode as a legacy fallback. Any static documentation site generator (Jekyll, Hugo, Astro, Docusaurus) speaks Markdown natively; none speak BBCode. If you're archiving forum content for long-term readability, Markdown is the format that will still render correctly in fifteen years.

There's also a searchability benefit. BBCode was tied to a specific rendering engine (phpBB's PHP parser, vBulletin's, etc). The rendered HTML was often inconsistent between platforms, and the source text — with [url=...]...[/url] wrappers and [b]...[/b] tags scattered through — is unpleasant to grep. Markdown source is approximately readable as-is, which makes archived content more useful for anyone browsing or searching offline.

The migration also flattens platform-specific tag dialects. Different forum platforms supported slightly different BBCode variants — some supported [spoiler], some had [user=123] mentions, some had [highlight]. Converting to Markdown forces a normalization pass: everything becomes standard MD, and you make deliberate decisions about what to keep versus drop.

Manual approach

BBCode is simple enough to hand-convert for small amounts of content. The common tags:

• [b]bold[/b] → **bold**
• [i]italic[/i] → *italic*
• [s]strike[/s] → ~~strike~~
• [u]underline[/u] → no direct MD equivalent; use **underline** as fallback or inline HTML <u>...</u>
• [url]http://example.com[/url] → <http://example.com> (autolink)
• [url=http://example.com]Display Text[/url] → [Display Text](http://example.com)
• [img]http://example.com/cat.jpg[/img] → ![](http://example.com/cat.jpg)
• [quote]text[/quote] → each line prefixed with >
• [quote="Author"]text[/quote] → > **Author** followed by > text
• [code]code[/code] → triple-backtick fenced block
• [list][*]item 1[*]item 2[/list] → dash-bulleted list
• [list=1][*]first[*]second[/list] → numbered list

A single forum post of moderate length (a few paragraphs, a quote, maybe a code sample) takes three to five minutes to hand-convert. A forum thread of twenty replies takes an hour.

Where hand-conversion gets slow: nested tags ([quote][b]Author said:[/b] text[/quote]), platform-specific tags you have to decide how to handle, and [color] / [size] / [font] wrappers that carry styling the target platform can't reproduce.

For a forum archive of hundreds or thousands of posts, hand-conversion is not realistic. Use a tool.

Automated approach (our tool)

Our converter implements common BBCode tag coverage. You paste a post or thread, get Markdown out. Coverage:

• Inline formatting: [b] / [i] / [s] / [u] with their expected Markdown mappings (**, *, ~~, ** fallback for underline)
• Links: both [url]X[/url] (autolink form) and [url=X]Y[/url] (display-text form) convert correctly
• Images: [img]X[/img] becomes a Markdown image with empty alt text
• Quotes: anonymous [quote]x[/quote] becomes a line-prefixed blockquote; attributed [quote="Author"]x[/quote] becomes > **Author** followed by the content
• Code: [code]x[/code] becomes a fenced code block. Language is not preserved (BBCode's [code=javascript] variants are less standard across platforms; we don't parse them)
• Lists: [list][*] becomes dash bullets; [list=1][*] becomes numbered items
• Styling wrappers: [color=red]x[/color] and [size=14]x[/size] have their content preserved and the wrapper stripped. Color and size do not translate to Markdown.

Not covered: forum-specific tags ([spoiler], [member=123], [highlight], etc.) pass through as literal text so you can spot-edit them. Nested mixed-type tags (e.g. a [list] inside a [quote]) may have ordering issues — the engine applies lists first then inline, which can leave stray markers in edge cases.

The converter is pragmatic: it covers the patterns that appear in 95% of forum posts and lets the rare cases fall through as literal text rather than silently corrupting output.

Common gotchas

Nested quotes can flatten unexpectedly. [quote="A"][quote="B"]original[/quote] B's reply[/quote] is a common forum pattern — someone quoting a previous quote to reply with context. Our engine converts the outer and inner quotes separately, but the line-prefix logic for the outer quote adds > to every line including the ones already inside > . You end up with >> double-blockquote prefixes, which is actually correct Markdown nested blockquote syntax — but check rendering in your destination to confirm it looks right.

Underline as bold loses intent. BBCode [u]text[/u] becomes **text** in our output. If your forum archive uses underline for a specific distinguishing purpose (e.g. marking direct quotes, highlighting rules) and you need to preserve the distinction, either (a) pre-process the source to use different wrappers for different uses, or (b) post-process the output to replace specific [u] content back to inline HTML <u>...</u> where the distinction matters.

Color and size vanish. [color=red]URGENT[/color] becomes just URGENT in the output. If the color or size was carrying information (e.g. a moderator's red text marked a rule notice), you lose that signal. For moderator formatting, consider a pre-processing pass that wraps colored content in a recognizable marker: [color=red]X[/color] → **⚠️ X** before running through our tool.

Links in URL without http:// prefix. Some BBCode usages have bare domains: [url=example.com]link[/url]. These convert to [link](example.com), which many Markdown renderers won't treat as a link because the protocol is missing. Post-process the output to add http:// prefixes to bare domains if your renderer is strict.

Image alt text is empty. [img]cat.jpg[/img] becomes ![](cat.jpg) with empty alt. BBCode had no alt-text convention. For accessibility and SEO, you may want to hand-add alt text after conversion. A script that prompts for each image during a review pass is one way; otherwise, leave the alts blank (marked for review) and come back to them later.

List items run together in some edge cases. Our engine handles [list][*]a[*]b[/list] by splitting on [*]. If your source has unusual whitespace or newline patterns (common from copy-paste of formatted posts), items may merge or split unexpectedly. Check list output for merged items or stray bullet markers.

Custom tags visible in output. Forum-specific tags like [spoiler]content[/spoiler] or [member=123]Alice[/member] pass through as literal text. Our engine can't know what your platform meant by these. For common custom tags, add a pre-conversion search-and-replace: [spoiler]x[/spoiler] → <details><summary>Spoiler</summary>x</details> (HTML works in most Markdown renderers), [member=\d+](.+?)[/member] → **$1**, etc.

Code blocks lack syntax highlighting. Our [code] → fenced-code conversion doesn't preserve language hints even if the source used [code=javascript]. After conversion, do a pass to add language hints to code blocks where your forum context suggests them (e.g. a JavaScript forum → add javascript to every bare fence).

When to use Pandoc instead

Pandoc does not have a native BBCode reader. For BBCode-specific conversion, our tool is actually one of the better free options — most BBCode → Markdown converters are forum-specific (phpBB plugins, vBulletin tools) rather than platform-neutral.

For forum migrations that involve structural content beyond posts — board hierarchy, user metadata, attachments — you need a platform-specific export tool. Discourse's importers handle phpBB, vBulletin, SMF, XenForo, and others directly, preserving thread structure and converting BBCode to Markdown as part of the import. If your migration target is Discourse, use its importer rather than converting files individually.

For bulk archive preservation (just the text content, formatted nicely for reading), our tool paired with a simple script to process forum-export dumps is the right approach.

Migration workflow

A workflow for rescuing BBCode forum content to Markdown:

1. Export from the source platform. Most forum software has an export option — phpBB supports SQL dumps, vBulletin has backup tools, many platforms offer per-thread export. Get the content out in whatever format the platform provides.
2. Extract just the post content. Forum exports often include metadata (user IDs, timestamps, post IDs) wrapped around the actual BBCode. Write a script that pulls out just the post_content field per post and pairs it with a filename based on thread + post ID.
3. Pre-process platform-specific tags. Write search-and-replace passes for any custom tags your platform used: [spoiler] → HTML details block, [member=N] → a link or bold, [youtube]X[/youtube] → a proper YouTube link. Do this before conversion.
4. Convert each post via our tool. For small archives, paste and convert one by one. For larger archives, the same logic (regex pipeline) implemented in a script over the exported files is faster — our tool's source is also available as a package if you want to call it programmatically.
5. Reassemble threads. A forum thread is a sequence of posts. For readable output, concatenate posts with author attribution and timestamp headers: ## [Post by Alice, 2011-03-14](...) followed by the converted content.
6. Handle attachments. If posts had image attachments hosted on the forum, download them and rewrite the image references in the Markdown to point to a local folder or a CDN you control.
7. Build a destination index. Create a top-level README or index page listing threads by topic, date, or frequency. Forum content loses navigation when you flatten it to files; the index restores findability.
8. Preview the rendered output. Open a sample of converted threads in your destination (an Obsidian vault, a Hugo site, a static HTML dump) and spot-check that quotes render, lists are correct, images display, and the overall reading experience is usable.

A 500-post forum archive takes a full day of setup (platform export, scripting) plus an hour or two of conversion and review. Larger archives scale linearly with scripting investment, not manually-adjusted per-post work.