bbcode

README

lucid-bbcode

lucid-bbcode is a standalone, dependency-free Go renderer for the BBCode behavior used by sober_bbcode. It produces escaped HTML, supports the core formatting, list, table, image, and URL tags, and does not share mutable configuration between calls.

The module requires Go 1.26.5.

html := bbcode.Render("[b]bold[/b] and [url=https://example.com]a link[/url]")
// <strong>bold</strong> and <a href="https://example.com">a link</a>

Raw Extensions

Markdown deliberately does not belong to this module. A higher-level package such as lucid-markup can register a raw tag and own its Markdown renderer and sanitization policy:

html := bbcode.Render("[markdown]**literal BBCode**[/markdown]",
	bbcode.WithTag(bbcode.TagDefinition{
		Name: "markdown",
		Raw:  true,
		RenderRaw: func(source string) string {
			return renderMarkdown(source)
		},
	}),
)

The raw callback receives the content between the matching tags without BBCode parsing. Its return value is emitted as HTML, so the callback owner is responsible for producing safe output.

Compatibility

The test suite ports the verified behavioral core of sober_bbcode at 433ab637a5ac9a55aef937fbb6b2bbfac2086f40, including article and real-world post corpora. Markdown-specific upstream examples are intentionally excluded from this package.

License

MIT. See LICENSE.

Documentation

Overview

Package bbcode renders BBCode input as safe HTML.

Index

• func Render(input string, options ...Option) string
• type Config
  • func NewConfig() *Config
  • func (config *Config) AddTag(definition TagDefinition)
• type Node
• type Option
  • func WithTag(definition TagDefinition) Option
• type Root
  • func Parse(input string, options ...Option) *Root
• type Tag
• type TagDefinition
• type Text

Functions

func Render

func Render(input string, options ...Option) string

Render converts BBCode input into safe HTML.

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config holds the tag definitions used during a Parse or Render call.

A fresh configuration is created for every call, so options cannot affect unrelated renders.

func NewConfig

func NewConfig() *Config

NewConfig returns an independent configuration with the built-in tags.

func (*Config) AddTag

func (config *Config) AddTag(definition TagDefinition)

AddTag adds or replaces a tag definition. Names are normalized to lower case.

type Node

type Node interface {
	// contains filtered or unexported methods
}

Node is an element in a parsed BBCode document.

type Option

type Option func(*Config)

Option changes the tag configuration used for one Parse or Render call.

func WithTag

func WithTag(definition TagDefinition) Option

WithTag adds or replaces one tag definition for a Parse or Render call.

type Root

type Root struct {
	Children []Node
}

Root is the top-level node of a parsed BBCode document.

func Parse

func Parse(input string, options ...Option) *Root

Parse converts BBCode input into a document tree.

type Tag

type Tag struct {
	Name         string
	Attribute    string
	HasAttribute bool
	Children     []Node
}

Tag is a recognized BBCode tag and its nested content.

type TagDefinition

type TagDefinition struct {
	Name            string
	HTMLTag         string
	Priority        int
	Void            bool
	VoidIfAttribute bool
	HTMLVoid        bool
	Attributes      []string
	Raw             bool
	AutoClose       bool
	RenderRaw       func(string) string
}

TagDefinition describes how one BBCode tag is parsed and rendered.

type Text

type Text struct {
	Content string
	// contains filtered or unexported fields
}

Text is literal content in a parsed BBCode document.