Documentation
¶
Overview ¶
Package md provides markdown conversion utilities for Confluence.
macro.go defines the core data structures for macro parsing.
parser.go defines shared types for macro parsing in both directions.
parser_bracket.go parses bracket syntax [MACRO]...[/MACRO] into MacroNode trees.
parser_xml.go parses Confluence XML into MacroNode trees.
render.go provides functions to render MacroNodes to Confluence storage format.
tokenizer_bracket.go implements tokenization for [MACRO]...[/MACRO] bracket syntax.
tokenizer_xml.go implements tokenization for Confluence storage format XML.
tokens.go defines token types for macro parsing in both directions.
Index ¶
- Variables
- func ExtractCDATAContent(s string) string
- func FormatPlaceholder(id int) string
- func FromConfluenceStorage(html string) (string, error)
- func FromConfluenceStorageWithOptions(html string, opts ConvertOptions) (string, error)
- func RenderMacroToBracket(node *MacroNode) string
- func RenderMacroToBracketOpen(node *MacroNode) string
- func RenderMacroToXML(node *MacroNode) string
- func ToADF(markdown []byte) (string, error)
- func ToConfluenceStorage(markdown []byte) (string, error)
- type ADFDocument
- type ADFMark
- type ADFNode
- type BodyType
- type BracketToken
- type BracketTokenType
- type ConvertOptions
- type MacroNode
- type MacroType
- type ParseResult
- type Segment
- type SegmentType
- type XMLToken
- type XMLTokenType
Constants ¶
This section is empty.
Variables ¶
var MacroRegistry = map[string]MacroType{ "toc": { Name: "toc", HasBody: false, }, "info": { Name: "info", HasBody: true, BodyType: BodyTypeRichText, }, "warning": { Name: "warning", HasBody: true, BodyType: BodyTypeRichText, }, "note": { Name: "note", HasBody: true, BodyType: BodyTypeRichText, }, "tip": { Name: "tip", HasBody: true, BodyType: BodyTypeRichText, }, "expand": { Name: "expand", HasBody: true, BodyType: BodyTypeRichText, }, "code": { Name: "code", HasBody: true, BodyType: BodyTypePlainText, }, }
MacroRegistry maps macro names to their type definitions. Adding a new macro = adding one entry here.
Functions ¶
func ExtractCDATAContent ¶
ExtractCDATAContent extracts content from a CDATA section. Input: "<![CDATA[content]]>" Output: "content"
func FormatPlaceholder ¶
FormatPlaceholder creates a macro placeholder string.
func FromConfluenceStorage ¶
FromConfluenceStorage converts Confluence storage format (XHTML) to markdown.
func FromConfluenceStorageWithOptions ¶
func FromConfluenceStorageWithOptions(html string, opts ConvertOptions) (string, error)
FromConfluenceStorageWithOptions converts Confluence storage format (XHTML) to markdown with configurable options.
func RenderMacroToBracket ¶
RenderMacroToBracket converts a MacroNode back to bracket syntax.
func RenderMacroToBracketOpen ¶
RenderMacroToBracketOpen renders just the opening bracket tag (without body or close).
func RenderMacroToXML ¶
RenderMacroToXML converts a MacroNode to Confluence XML storage format.
func ToADF ¶
ToADF converts markdown content to Atlassian Document Format (ADF) JSON. The returned string is a JSON-encoded ADF document.
func ToConfluenceStorage ¶
ToConfluenceStorage converts markdown content to Confluence storage format (XHTML).
Types ¶
type ADFDocument ¶
type ADFDocument struct {
Type string `json:"type"`
Version int `json:"version"`
Content []*ADFNode `json:"content"`
}
ADFDocument represents an Atlassian Document Format document.
type ADFMark ¶
type ADFMark struct {
Type string `json:"type"`
Attrs map[string]interface{} `json:"attrs,omitempty"`
}
ADFMark represents a text mark (formatting) in ADF.
type ADFNode ¶
type ADFNode struct {
Type string `json:"type"`
Attrs map[string]interface{} `json:"attrs,omitempty"`
Content []*ADFNode `json:"content,omitempty"`
Text string `json:"text,omitempty"`
Marks []*ADFMark `json:"marks,omitempty"`
}
ADFNode represents a node in an ADF document.
type BodyType ¶
type BodyType string
BodyType indicates how a macro's body content should be handled.
type BracketToken ¶
type BracketToken struct {
Type BracketTokenType
MacroName string // set for OpenTag, CloseTag, SelfClose (uppercase for matching)
OriginalName string // set for OpenTag, CloseTag, SelfClose (original case for reconstruction)
Parameters map[string]string // set for OpenTag, SelfClose
Text string // set for Text tokens
Position int // byte offset in original input
OriginalTagText string // the full original bracket text for unknown macro reconstruction
}
BracketToken represents a single token from bracket syntax parsing.
func TokenizeBrackets ¶
func TokenizeBrackets(input string) ([]BracketToken, error)
TokenizeBrackets scans input for bracket macro syntax and returns a token stream. Recognized forms:
- [MACRO] or [MACRO params] - open tag
- [/MACRO] - close tag
- [MACRO/] - self-closing (no body)
Text between macros is returned as BracketTokenText tokens. Unknown macro names are still tokenized (validation happens in parser).
type BracketTokenType ¶
type BracketTokenType int
BracketTokenType represents token types for bracket syntax [MACRO]...[/MACRO]
const ( BracketTokenText BracketTokenType = iota // plain text between macros BracketTokenOpenTag // [MACRO] or [MACRO params] BracketTokenCloseTag // [/MACRO] BracketTokenSelfClose // [MACRO/] (no body) )
type ConvertOptions ¶
type ConvertOptions struct {
// ShowMacros shows placeholder text for Confluence macros instead of stripping them.
ShowMacros bool
}
ConvertOptions configures the HTML to markdown conversion.
type MacroNode ¶
type MacroNode struct {
Name string // "toc", "info", "warning", etc.
Parameters map[string]string // key-value pairs from macro attributes
Body string // raw content for body macros
Children []*MacroNode // nested macros within body
}
MacroNode represents a parsed macro in either direction (MD↔XHTML).
type MacroType ¶
type MacroType struct {
Name string // canonical lowercase name
HasBody bool // true for panels/expand/code, false for TOC
BodyType BodyType // how to handle body content
}
MacroType defines the behavior for a specific macro.
func LookupMacro ¶
LookupMacro returns the MacroType for a given name, normalizing to lowercase. Returns ok=false if macro is not registered.
type ParseResult ¶
type ParseResult struct {
Segments []Segment
Warnings []string // any warnings generated during parsing
}
ParseResult contains the parsed output: a sequence of segments that alternate between text content and macro nodes.
func ParseBracketMacros ¶
func ParseBracketMacros(input string) (*ParseResult, error)
ParseBracketMacros parses bracket macro syntax and returns a ParseResult. Input: markdown with [MACRO]...[/MACRO] syntax Output: segments of text and MacroNode trees
func ParseConfluenceXML ¶
func ParseConfluenceXML(input string) (*ParseResult, error)
ParseConfluenceXML parses Confluence storage format XML and returns a ParseResult. Input: XHTML with <ac:structured-macro> elements Output: segments of text/HTML and MacroNode trees
func (*ParseResult) AddMacroSegment ¶
func (pr *ParseResult) AddMacroSegment(macro *MacroNode)
AddMacroSegment appends a macro segment.
func (*ParseResult) AddTextSegment ¶
func (pr *ParseResult) AddTextSegment(text string)
AddTextSegment appends a text segment, merging with previous text if possible.
func (*ParseResult) AddWarning ¶
func (pr *ParseResult) AddWarning(format string, args ...interface{})
AddWarning logs a warning and stores it in the result.
func (*ParseResult) GetMacros ¶
func (pr *ParseResult) GetMacros() []*MacroNode
GetMacros returns all MacroNodes from the parse result.
type Segment ¶
type Segment struct {
Type SegmentType
Text string // set when Type == SegmentText
Macro *MacroNode // set when Type == SegmentMacro
}
Segment represents either text content or a parsed macro.
type SegmentType ¶
type SegmentType int
SegmentType indicates whether a segment is text or a macro.
const ( SegmentText SegmentType = iota // plain text/HTML content SegmentMacro // parsed macro node )
type XMLToken ¶
type XMLToken struct {
Type XMLTokenType
MacroName string // set for OpenTag
ParamName string // set for Parameter
Value string // parameter value or body type ("rich-text" or "plain-text")
Text string // set for Text tokens
Position int // byte offset in original input
}
XMLToken represents a single token from Confluence XML parsing.
func TokenizeConfluenceXML ¶
TokenizeConfluenceXML scans input for Confluence storage format macros and returns a token stream. This tokenizer produces a flat stream of tokens that the parser will assemble into a tree.
type XMLTokenType ¶
type XMLTokenType int
XMLTokenType represents token types for Confluence XML parsing.
const ( XMLTokenText XMLTokenType = iota // text/HTML between macros XMLTokenOpenTag // <ac:structured-macro ac:name="..."> XMLTokenCloseTag // </ac:structured-macro> XMLTokenParameter // <ac:parameter ac:name="...">value</ac:parameter> XMLTokenBody // <ac:rich-text-body> or <ac:plain-text-body> XMLTokenBodyEnd // </ac:rich-text-body> or </ac:plain-text-body> )
Source Files