README
¶
md2adf
⚠️ Work in Progress: This package is currently under active development and is not yet ready for production use. APIs may change without notice.
A Go package that converts Markdown to Atlassian Document Format (ADF).
Features
- ✅ CommonMark Compliant: Built on top of goldmark, a strict CommonMark parser
- ✅ GitHub Flavored Markdown: Full support for GFM extensions (tables, task lists, strikethrough)
- ✅ Type-Safe: ADF structures are modeled as Go structs with full type safety
- ✅ Extensible: Configurable via functional options pattern
- ✅ Well-Tested: Comprehensive test coverage
Supported Markdown Elements
Block Elements
- Paragraphs
- Headings (levels 1-6)
- Code blocks (fenced and indented)
- Blockquotes
- Horizontal rules
- Ordered and unordered lists
- Task lists (GFM)
- Tables (GFM)
Inline Elements
- Bold and italic text
- Links (inline and autolinks)
- Inline code
- Strikethrough (GFM)
- Hard line breaks
Installation
go get github.com/hrko/md2adf
Usage
Basic Usage
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`# Hello, World!
This is a **bold** and *italic* text.
- Item 1
- Item 2
`)
// Convert Markdown to ADF JSON
adfJSON, err := md2adf.Convert(markdown)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(adfJSON))
}
With Options
// Disable GFM extensions
adfJSON, err := md2adf.Convert(markdown, md2adf.WithGFM(false))
// Custom handler for unsupported nodes
handler := func(nodeKind string) error {
log.Printf("Warning: unsupported node type: %s", nodeKind)
return nil // Continue conversion
}
adfJSON, err := md2adf.Convert(markdown, md2adf.WithUnsupportedHandler(handler))
Converting to Document Struct
// Get the ADF document as a Go struct
doc, err := md2adf.ConvertToDocument(markdown)
if err != nil {
log.Fatal(err)
}
// Work with the document programmatically
for _, block := range doc.Content {
// Process blocks
}
Examples
Task List
Input:
- [ ] Todo item
- [x] Done item
Output (ADF JSON):
{
"version": 1,
"type": "doc",
"content": [
{
"type": "taskList",
"content": [
{
"type": "taskItem",
"attrs": {
"localId": "task-1",
"state": "TODO"
},
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Todo item"
}
]
}
]
},
{
"type": "taskItem",
"attrs": {
"localId": "task-2",
"state": "DONE"
},
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Done item"
}
]
}
]
}
]
}
]
}
Table
Input:
| Name | Age |
|-------|-----|
| Alice | 30 |
| Bob | 25 |
Output: Converted to ADF table structure with headers and cells.
Architecture
The package follows a pipeline architecture:
- Parse: goldmark parses Markdown into an AST
- Render: Custom ADF renderer traverses the AST and builds ADF structures
- Marshal: Go structs are marshaled to JSON
The custom renderer implements goldmark's renderer.Renderer interface, allowing it to directly translate the AST into ADF-compliant Go structs.
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Documentation
¶
Overview ¶
Package md2adf converts Markdown to Atlassian Document Format (ADF).
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Convert ¶
Convert transforms Markdown source text ([]byte) into an Atlassian Document Format (ADF) JSON representation ([]byte). The conversion process can be customized via ...Option arguments.
Example ¶
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`# Hello, World!
This is a paragraph with **bold** and *italic* text.`)
adfJSON, err := md2adf.Convert(markdown)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(adfJSON))
// Output will be ADF JSON
}
Output:
Example (WithGFM) ¶
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`- [ ] Todo item
- [x] Done item`)
// GFM is enabled by default
adfJSON, err := md2adf.Convert(markdown)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(adfJSON))
// Task list will be converted to ADF taskList
}
Output:
func ConvertToDocument ¶
ConvertToDocument is a convenience function that converts Markdown to an ADF Document struct. This can be useful if you want to work with the ADF structure programmatically before marshaling to JSON.
Example ¶
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`# Heading
Paragraph text.`)
// Get ADF as a Go struct
doc, err := md2adf.ConvertToDocument(markdown)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Document version: %d\n", doc.Version)
fmt.Printf("Document type: %s\n", doc.Type)
fmt.Printf("Number of blocks: %d\n", len(doc.Content))
}
Output:
Types ¶
type Option ¶
type Option func(*config)
Option is a functional option for configuring the conversion process.
func WithGFM ¶
WithGFM enables or disables GitHub Flavored Markdown extensions (tables, task lists, strikethrough). Default is enabled (true).
Example ¶
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`Some markdown text`)
// Disable GFM extensions
adfJSON, err := md2adf.Convert(markdown, md2adf.WithGFM(false))
if err != nil {
log.Fatal(err)
}
fmt.Println(string(adfJSON))
}
Output:
func WithUnsupportedHandler ¶
func WithUnsupportedHandler(handler UnsupportedNodeHandler) Option
WithUnsupportedHandler sets a custom handler for unsupported Markdown nodes. By default, unsupported nodes are silently ignored.
Example ¶
package main
import (
"fmt"
"log"
"github.com/hrko/md2adf"
)
func main() {
markdown := []byte(`# Heading`)
// Log unsupported nodes
handler := func(nodeKind string) error {
log.Printf("Unsupported node: %s", nodeKind)
return nil
}
adfJSON, err := md2adf.Convert(markdown, md2adf.WithUnsupportedHandler(handler))
if err != nil {
log.Fatal(err)
}
fmt.Println(string(adfJSON))
}
Output:
type UnsupportedNodeHandler ¶
UnsupportedNodeHandler is a function type for handling Markdown nodes that don't have a direct ADF equivalent.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adf provides data structures for the Atlassian Document Format (ADF).
|
Package adf provides data structures for the Atlassian Document Format (ADF). |
|
cmd
|
|
|
md2confluence
command
|
|
|
Package renderer implements a custom goldmark renderer that outputs ADF JSON.
|
Package renderer implements a custom goldmark renderer that outputs ADF JSON. |