adfmarkdown

README

adf-to-markdown

Go library for converting Atlassian Document Format (ADF) JSON into Markdown.

Contributing

See CONTRIBUTING.md for local development, testing, versioning, and release workflow details.

Requirements

• Go 1.25+
• GOEXPERIMENT=jsonv2 enabled (this library uses encoding/json/v2)

Install

go get github.com/ajbeck/adf-to-markdown

Generate (Before Build/Test)

If your project uses code generation, run:

GOEXPERIMENT=jsonv2 go generate ./...

Then run tests:

GOEXPERIMENT=jsonv2 go test ./...

Note: this repository is safe to run with go generate ./... even when no generators are configured.

Basic Usage

package main

import (
	"fmt"
	"log"

	adfmarkdown "github.com/ajbeck/adf-to-markdown"
)

func main() {
	input := []byte(`{
		"version": 1,
		"type": "doc",
		"content": [
			{
				"type": "heading",
				"attrs": {"level": 2},
				"content": [{"type": "text", "text": "Overview"}]
			},
			{
				"type": "paragraph",
				"content": [{"type": "text", "text": "Hello from ADF"}]
			}
		]
	}`)

	md, err := adfmarkdown.UnmarshalADF(input)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(md))
}

Run with:

GOEXPERIMENT=jsonv2 go run .

Writing to an io.Writer

var buf bytes.Buffer
err := adfmarkdown.UnmarshalADFTo(&buf, adfJSON)

Using a Typed Package in a Consuming App

In your app, keep API payloads typed (for example in internal/jiratypes) and pass the typed ADF field to this library.

package jiratypes

type Document struct {
	Version int    `json:"version"`
	Type    string `json:"type"`
	Content []Node `json:"content"`
}

type Node struct {
	Type    string         `json:"type"`
	Attrs   map[string]any `json:"attrs,omitempty"`
	Content []Node         `json:"content,omitempty"`
	Text    string         `json:"text,omitempty"`
}

type Issue struct {
	Fields struct {
		Description Document `json:"description"`
	} `json:"fields"`
}

package main

import (
	"encoding/json"
	"fmt"
	"log"

	adfmarkdown "github.com/ajbeck/adf-to-markdown"
	"yourmodule/internal/jiratypes"
)

func renderIssueDescription(issueJSON []byte) (string, error) {
	var issue jiratypes.Issue
	if err := json.Unmarshal(issueJSON, &issue); err != nil {
		return "", err
	}

	adfBytes, err := json.Marshal(issue.Fields.Description)
	if err != nil {
		return "", err
	}

	md, err := adfmarkdown.UnmarshalADF(adfBytes)
	if err != nil {
		return "", err
	}
	return string(md), nil
}

func main() {
	md, err := renderIssueDescription([]byte(`{"fields":{"description":{"version":1,"type":"doc","content":[]}}}`))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(md)
}

Useful Options

• WithStrictSchema(bool)
• WithBuiltInSchemaValidation(bool)
• WithAllowUnsupportedNodes(bool)
• WithHardBreakStyle(...)
• WithCodeFenceStyle(...)
• WithSchemaValidator(func([]byte) error)
• WithUnsupportedBlockHandler(...)
• WithUnsupportedInlineHandler(...)
• WithExtensionBlockHandler(...)
• WithExtensionInlineHandler(...)

Error Handling

The library returns typed errors:

• *adfmarkdown.Error with fields:
• Path (ADF path, e.g. /content/0/content/1)
• Kind (adfmarkdown.ErrorKind)
• Detail
• Cause (wrapped error; available via errors.Unwrap / errors.As)

Common ErrorKind values include:

• ErrKindInvalidRoot
• ErrKindInvalidJSON
• ErrKindMissingType
• ErrKindUnsupportedNode
• ErrKindUnsupportedInline
• ErrKindUnsupportedMark
• ErrKindInvalidAttr
• ErrKindInvalidMark
• ErrKindInvalidMarkCombo
• ErrKindInvalidStructure
• ErrKindInvalidText

v1 Compatibility Contract

• Build/runtime requirements: Go 1.25+ and GOEXPERIMENT=jsonv2.
• Stable entry points (v1): UnmarshalADF, UnmarshalADFTo.
• Stable options (v1): WithStrictSchema, WithBuiltInSchemaValidation, WithAllowUnsupportedNodes, WithHardBreakStyle, WithCodeFenceStyle, WithSchemaValidator, WithUnsupportedBlockHandler, WithUnsupportedInlineHandler, WithExtensionBlockHandler, WithExtensionInlineHandler.
• Stable error surface (v1): returned typed error *adfmarkdown.Error and the ErrorKind constants listed above.

Tests

GOEXPERIMENT=jsonv2 go test ./...

Or via make:

make test
make test-nojsonv2

Fuzzing

GOEXPERIMENT=jsonv2 go test -fuzz=FuzzUnmarshalADF -run=^$ ./...

Or via make:

make fuzz

Benchmarks

GOEXPERIMENT=jsonv2 go test -run=^$ -bench=BenchmarkUnmarshalADF -benchmem ./...

Or via make:

make bench

Documentation

Index

• func UnmarshalADF([]byte, ...Option) ([]byte, error)
• func UnmarshalADFTo(io.Writer, []byte, ...Option) error
• type CodeFenceStyle
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorKind
• type ExtensionBlockHandler
• type ExtensionInlineHandler
• type HardBreakStyle
• type Option
  • func WithAllowUnsupportedNodes(bool) Option
  • func WithBuiltInSchemaValidation(bool) Option
  • func WithCodeFenceStyle(CodeFenceStyle) Option
  • func WithExtensionBlockHandler(ExtensionBlockHandler) Option
  • func WithExtensionInlineHandler(ExtensionInlineHandler) Option
  • func WithHardBreakStyle(HardBreakStyle) Option
  • func WithSchemaValidator(func([]byte) error) Option
  • func WithStrictSchema(bool) Option
  • func WithUnsupportedBlockHandler(UnsupportedBlockHandler) Option
  • func WithUnsupportedInlineHandler(UnsupportedInlineHandler) Option
• type UnsupportedBlockHandler
• type UnsupportedInlineHandler

Functions

func UnmarshalADF

func UnmarshalADF([]byte, ...Option) ([]byte, error)

func UnmarshalADFTo

func UnmarshalADFTo(io.Writer, []byte, ...Option) error

Types

type CodeFenceStyle

type CodeFenceStyle string

type Error

type Error struct {
	Path   string
	Kind   ErrorKind
	Detail string
	Cause  error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorKind

type ErrorKind string

const (
	ErrKindInvalidRoot       ErrorKind = "invalid_root"
	ErrKindInvalidJSON       ErrorKind = "invalid_json"
	ErrKindMissingType       ErrorKind = "missing_type"
	ErrKindUnsupportedNode   ErrorKind = "unsupported_node"
	ErrKindUnsupportedInline ErrorKind = "unsupported_inline"
	ErrKindUnsupportedMark   ErrorKind = "unsupported_mark"
	ErrKindInvalidAttr       ErrorKind = "invalid_attr"
	ErrKindInvalidMark       ErrorKind = "invalid_mark"
	ErrKindInvalidMarkCombo  ErrorKind = "invalid_mark_combo"
	ErrKindInvalidStructure  ErrorKind = "invalid_structure"
	ErrKindInvalidText       ErrorKind = "invalid_text"
)

type ExtensionBlockHandler

type ExtensionBlockHandler func(nodeType, key, path string) (markdown string, handled bool, err error)

type ExtensionInlineHandler

type ExtensionInlineHandler func(nodeType, key, path string) (markdown string, handled bool, err error)

type HardBreakStyle

type HardBreakStyle string

type Option

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

func WithAllowUnsupportedNodes

func WithAllowUnsupportedNodes(bool) Option

func WithBuiltInSchemaValidation

func WithBuiltInSchemaValidation(bool) Option

func WithCodeFenceStyle

func WithCodeFenceStyle(CodeFenceStyle) Option

func WithExtensionBlockHandler

func WithExtensionBlockHandler(ExtensionBlockHandler) Option

func WithExtensionInlineHandler

func WithExtensionInlineHandler(ExtensionInlineHandler) Option

func WithHardBreakStyle

func WithHardBreakStyle(HardBreakStyle) Option

func WithSchemaValidator

func WithSchemaValidator(func([]byte) error) Option

func WithStrictSchema

func WithStrictSchema(bool) Option

func WithUnsupportedBlockHandler

func WithUnsupportedBlockHandler(UnsupportedBlockHandler) Option

func WithUnsupportedInlineHandler

func WithUnsupportedInlineHandler(UnsupportedInlineHandler) Option

type UnsupportedBlockHandler

type UnsupportedBlockHandler func(nodeType, path string) (markdown string, handled bool, err error)

type UnsupportedInlineHandler

type UnsupportedInlineHandler func(nodeType, path string) (markdown string, handled bool, err error)