MarkdigToBBCode 1.0.1

BBCode-Markdown Conversion Library

AI Development Disclaimer

This paragraph isn't AI generated. This library is my first attempt at actually using AI tools to write a library. It works better than I want to admit, especially when you focus it to take small steps and guide it to write code that passes tests. The other paragraphs of this readme are AI generated. I'm sorry, I hate documentation. And writing code apparently.

I initially used Google Gemini to design the fundamental approach but quickly got tired of the copy-pasting and sync work it requires, so I switched to VS26 with CoPilot integration halfway through.

Brief overview

A focused, two-way conversion library that reliably translates between Markdown and BBCode. It uses Markdig to produce a Markdown AST and a compact, test-driven BBCode parser. The library prioritizes deterministic, loss-minimizing conversions, correct nesting, and straightforward extensibility for custom tags. Target framework: .NET 8.

Key features

• Bi-directional conversion: Markdown → BBCode and BBCode → Markdown.
• Preserves structure and nesting for headings, lists, links, images, code, emphasis, quotes, and horizontal rules.
• Extensible renderer and element model for custom BBCode tags or custom Markdown mappings.
• Diagnostics for mismatched tags and best-effort recovery during parsing.
• Minimal external dependency: Markdig.

Architecture overview

The implementation separates parsing, conversion, rendering, and configuration into small, testable components.

• Parser layer

  • Markdig (Markdown → AST): yields Block and Inline nodes.
  • BBCode Tokenizer + Parser: converts raw BBCode into a token stream and then into BBCodeElement instances.

• Conversion / Renderer layer

  • Markdown → BBCode
    • BBCodeRenderer classes traverse Markdig nodes and emit BBCode fragments.
    • Each Markdig node type maps to a renderer class responsible for escaping, attributes, and tag emission.
  • BBCode → Markdown
    • BBCodeParser tokenizes input and maps tokens to concrete BBCodeElement subclasses (for example, BoldElement, UrlElement, CodeBlockElement).
    • An element visitor / renderer converts BBCodeElement instances into Markdown text. A stack-based nesting handler ensures correct open/close semantics and enables recovery from mismatches.

• Core models & infrastructure

  • BBCodeElement (base) with well-named subclasses.
  • RenderingContext to configure rules (heading size mapping, code-language handling, link strategies).
  • Tokenizer (single consolidated regex for initial tokenization) and a stack-based nest handler for robust parsing.
  • ConversionResult encapsulates Output and Diagnostics for consumers.

Design goals

• Deterministic outputs for identical inputs.
• Easy extensibility: add a new tag by implementing one small element class and registering its renderer.
• Thorough test coverage: unit tests for individual renderers/parsers and integration tests for round-trip stability.

Extensibility & integration points

• Add tags: implement a BBCodeElement subclass and register a renderer in the ElementFactory.
• Customize Markdown rendering: subclass BBCodeRenderer and override node renderers.
• Configure mappings in RenderingContext (e.g., map H1 to [size=24] vs [b][size=18]).
• Surface ConversionResult.Diagnostics to present parsing warnings/errors in host applications.

Error handling & edge cases

• Unknown tokens are emitted as plain text nodes — no silent data loss.
• Mismatched tags: stack handler attempts best-effort recovery and populates diagnostics.
• Ambiguous nesting and mixed inline/block content resolve deterministically per stack rules; tests cover representative scenarios.

Usage examples

1. Basic: Markdown → BBCode (Rendering)

string markdown = "# Project Status\n\n- Completed tasks.";
string bbCode = BBCodeRenderer.ToBBCode(markdown);
// renderer output: "[b][size=18]Project Status[/size][/b]\n\n[list]\n[*]Completed tasks.\n[/list]"

2. Basic: BBCode → Markdown (Parsing)

string bbCode = "[b]Final Report[/b][hr]Done.";
string markdown = BBCodeParser.ToMarkdown(bbCode);
// parser output: "**Final Report**\n---\nDone."

3. ASP.NET Core endpoint (quick integration)

[HttpPost("/convert")] 
public IActionResult Convert([FromBody] ConvertRequest req) 
{ 
  var converted = req.Format == "md-to-BB" ? MarkdownToBBCodeConverter.Convert(req.Content) : BBCodeParser.ToMarkdown(req.Content);
}

4. Batch migration script (archive migration)

foreach (var file in Directory.EnumerateFiles("archives", "*.BBcode"))
{
  var BB = File.ReadAllText(file);
  var md = BBCodeParser.ToMarkdown(BB);
  File.WriteAllText(Path.ChangeExtension(file, ".md"), md);
}

5. CLI / Tooling

• Use converters in CI or as a dotnet tool to migrate content in bulk or to validate round-trip stability.

6. Extending with a custom tag (concept)

• Implement CustomElement : BBCodeElement.
• Implement CustomElementRenderer to produce the desired Markdown or BBCode according to RenderingContext.
• Register the element/renderer pair in ElementFactory and add tests proving round-trip behavior.

Testing & contributing

• Add unit tests for new parser/renderer behavior and integration tests that verify round-trip stability.
• Follow the project's CONTRIBUTING.md and .editorconfig for formatting, testing, and branching rules.

Notes

• Target: .NET 8.
• Intended to be embeddable in libraries, web APIs, migration tools, and forum engines.