Convert BBCode to AsciiDoc

Why Convert BBCode to AsciiDoc?

Converting BBCode to AsciiDoc enables you to repurpose forum-based content for professional documentation and publishing. BBCode, while excellent for forum formatting, lacks the structural capabilities needed for technical writing, manuals, and books. AsciiDoc provides a complete documentation authoring platform that transforms simple forum posts into well-structured, professionally formatted documents suitable for any publishing medium.

AsciiDoc's semantic richness makes it the ideal target for BBCode conversion when documentation quality matters. Where BBCode offers basic text styling with tags like [b], [i], and [url], AsciiDoc provides a comprehensive document model with sections, cross-references, conditional content, admonition blocks, and mathematical notation. The conversion process intelligently maps BBCode tags to their AsciiDoc equivalents while adding opportunities for document structuring that BBCode simply cannot express.

The AsciiDoc ecosystem, centered around the Asciidoctor processor, enables powerful documentation workflows. After converting your BBCode content, you can integrate it into documentation pipelines that automatically generate websites, PDFs, and ebooks. Tools like Antora build multi-repository documentation sites from AsciiDoc sources, while Spring REST Docs generates API documentation directly from test cases. This ecosystem transforms static forum content into living, maintainable documentation.

For organizations migrating from forum-based knowledge management to structured documentation, BBCode to AsciiDoc conversion is a natural progression. AsciiDoc files integrate seamlessly with Git-based workflows, enabling code review for documentation changes, continuous integration builds, and automated deployment to documentation hosting platforms. This docs-as-code approach is increasingly adopted by software companies and open-source projects.

Key Benefits of Converting BBCode to AsciiDoc:

• Documentation-Grade Output: Produce publication-quality documents from forum content
• Single-Source Publishing: One AsciiDoc file generates HTML, PDF, EPUB, and more
• Semantic Structure: Add proper heading hierarchy, cross-references, and metadata
• Docs-as-Code: Integrate documentation into software development workflows
• Code Block Excellence: Syntax highlighting with language-specific formatting
• Extensible Platform: Custom extensions for diagrams, charts, and interactive content
• Industry Standard: Used by Red Hat, GitHub, Eclipse, and many tech organizations

Practical Examples

Example 1: Forum Guide to Technical Documentation

Input BBCode file (guide.bbcode):

[b]Server Setup Guide[/b]

[i]Last updated by Admin[/i]

[b]Requirements[/b]
[list]
[*]Ubuntu 22.04 LTS
[*]4GB RAM minimum
[*]20GB disk space
[/list]

[b]Step 1: Install Dependencies[/b]
[code]
sudo apt update
sudo apt install nginx postgresql
[/code]

[b]Step 2: Configure Firewall[/b]
[quote]Always enable the firewall before
exposing your server to the internet.[/quote]

[code]
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
[/code]

Output AsciiDoc file (guide.asciidoc):

= Server Setup Guide
Admin
:toc: left
:icons: font

_Last updated by Admin_

== Requirements

* Ubuntu 22.04 LTS
* 4GB RAM minimum
* 20GB disk space

== Step 1: Install Dependencies

[source,bash]
----
sudo apt update
sudo apt install nginx postgresql
----

== Step 2: Configure Firewall

WARNING: Always enable the firewall before
exposing your server to the internet.

[source,bash]
----
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
----

Example 2: Forum Discussion to Structured Report

Input BBCode file (discussion.bbcode):

[b]Bug Report: Login Failure on Mobile[/b]

[b]Description:[/b]
Users report [i]intermittent login failures[/i]
on mobile devices running iOS 17.

[b]Steps to Reproduce:[/b]
[list=1]
[*]Open the app on iPhone
[*]Enter credentials
[*]Tap "Login" button
[*]Observe error message
[/list]

[b]Error Log:[/b]
[code]
ERROR 2024-01-15 10:23:45 auth.login
SessionError: Token expired
Stack: AuthModule.validate()
[/code]

[img]https://bugs.example.com/screenshot.png[/img]

[quote="Developer"]Fixed in build 2.4.1.
Deploy scheduled for Friday.[/quote]

Output AsciiDoc file (discussion.asciidoc):

= Bug Report: Login Failure on Mobile

== Description

Users report _intermittent login failures_
on mobile devices running iOS 17.

== Steps to Reproduce

. Open the app on iPhone
. Enter credentials
. Tap "Login" button
. Observe error message

== Error Log

[source]
----
ERROR 2024-01-15 10:23:45 auth.login
SessionError: Token expired
Stack: AuthModule.validate()
----

image::https://bugs.example.com/screenshot.png[]

[quote, Developer]
____
Fixed in build 2.4.1.
Deploy scheduled for Friday.
____

Example 3: Forum Announcement to Newsletter

Input BBCode file (announcement.bbcode):

[b]Community Update - March 2026[/b]

[i]Hello everyone![/i]

We're excited to announce several updates:

[b]New Features:[/b]
[list]
[*][b]Dark Mode[/b] - Now available in settings
[*][b]File Sharing[/b] - Upload up to 50MB
[*][b]Notifications[/b] - Push alerts for replies
[/list]

For details visit [url=https://example.com/changelog]
our changelog[/url].

[b]Community Stats:[/b]
[list]
[*]Active users: 15,000+
[*]Posts this month: 42,000
[*]New members: 1,200
[/list]

Output AsciiDoc file (announcement.asciidoc):

= Community Update - March 2026

_Hello everyone!_

We're excited to announce several updates:

== New Features

* *Dark Mode* -- Now available in settings
* *File Sharing* -- Upload up to 50MB
* *Notifications* -- Push alerts for replies

For details visit
https://example.com/changelog[our changelog].

== Community Stats

* Active users: 15,000+
* Posts this month: 42,000
* New members: 1,200

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc file extensions?

A: Both .adoc and .asciidoc are valid extensions for AsciiDoc files, and they produce identical results. The .adoc extension is the shorter, more commonly used convention recommended by the Asciidoctor project. The .asciidoc extension is more descriptive and was the original convention. Both are fully supported by all AsciiDoc processors and tools.

Q: How does BBCode compare to AsciiDoc in terms of complexity?

A: BBCode is intentionally simple with about 15-20 basic tags, designed for non-technical forum users. AsciiDoc is a full document authoring language with hundreds of features including sections, cross-references, conditionals, macros, and custom extensions. The conversion process maps BBCode's simple tags to AsciiDoc equivalents, so the output remains readable even for users unfamiliar with AsciiDoc syntax.

Q: Can I use the converted AsciiDoc files with GitHub?

A: Yes! GitHub natively renders AsciiDoc files in repositories. Files with .adoc or .asciidoc extensions are automatically displayed with proper formatting in the GitHub web interface. This makes AsciiDoc an excellent choice for project documentation, README files, and wikis stored in Git repositories.

Q: What happens to BBCode [img] tags during conversion?

A: BBCode image tags like [img]url[/img] are converted to AsciiDoc's image macro syntax: image::url[]. If the BBCode includes size attributes, they are mapped to AsciiDoc's image attributes. The image URLs are preserved exactly, ensuring all images display correctly when the AsciiDoc document is rendered.

Q: Does the conversion handle nested BBCode tags?

A: Yes, nested BBCode tags like [b][i]bold italic[/i][/b] are properly converted to AsciiDoc's inline formatting: *_bold italic_*. The converter handles common nesting patterns including bold within italic, links within bold text, and formatted text within list items. Complex nesting is preserved with appropriate AsciiDoc syntax.

Q: Can I add a table of contents to the converted document?

A: Absolutely! AsciiDoc supports automatic table of contents generation. After conversion, simply add :toc: to the document header, and Asciidoctor will generate a navigable table of contents based on the section headings. You can customize placement (:toc: left, :toc: right) and depth (:toclevels: 3) as needed.

Q: What tools do I need to process the converted AsciiDoc files?

A: The primary tool is Asciidoctor, available as a Ruby gem (gem install asciidoctor), a Docker image, or integrated into build tools like Maven and Gradle. For PDF output, install asciidoctor-pdf. For diagrams, use asciidoctor-diagram. Many IDEs like IntelliJ IDEA and VS Code have AsciiDoc preview plugins available.

Q: How are BBCode [list] tags with numbered items converted?

A: BBCode numbered lists ([list=1]) are converted to AsciiDoc ordered lists using the dot notation (. Item). Unordered lists ([list] with [*] items) become AsciiDoc unordered lists using the asterisk notation (* Item). Nested lists are supported with additional dots or asterisks to indicate depth levels.