adf4j

Java tools for Atlassian Document Format (ADF). adf4j converts Confluence and Jira rich-text JSON to GitHub-Flavored Markdown, extracts document metadata, and validates ADF structure.

• Library: dev.nthings:adf4j, published to Maven Central.
• CLI: native executables for Linux, macOS, and Windows, attached to each GitHub release.
• WASM: @nthings.dev/adf4j-wasm, published to npm and attached to each GitHub release.

adf4j is immutable, thread-safe, dependency-light, and I/O-free. It never calls Confluence, a CDN, or a database. Page, media, attachment, and macro lookups stay in your application through resolver callbacks.

Warning

This project is maintained WITH AI agents assistance. While the output was reviewed and validated against a Confluence wiki containing roughly 2,000 pages, edge cases and unforeseen scenarios may remain. Please report any issues.

Install

<dependency>
    <groupId>dev.nthings</groupId>
    <artifactId>adf4j</artifactId>
    <version>1.0.0</version>
</dependency>

Build

This repo uses just as its task runner. Run just to list recipes; the same recipes back both local development and CI. Repository-level Node tasks require Node 24 or newer.

just verify   # compile, test, coverage gate, and format checks
just native   # GraalVM native CLI executable
just wasm     # GraalVM WASM web image
just chrome-ext # unpacked Confluence Cloud Chrome extension

Each recipe wraps the Maven wrapper, so ./mvnw verify and friends still work directly.

Convert ADF

import dev.nthings.adf4j.AdfToMarkdown;

AdfToMarkdown converter = AdfToMarkdown.create();
String markdown = converter.toMarkdown(adfJson);

Build one AdfToMarkdown and reuse it across documents and threads.

CLI

Download the archive for your platform from the latest release, extract it, and run adf4j-cli.

adf4j convert doc.adf.json
cat doc.adf.json | adf4j convert -t "My Page" -o out.md
adf4j analyze --select referencedFileIds,outline doc.adf.json
adf4j validate --fail-on-warning doc.adf.json

Input comes from a file argument or stdin. Stdout contains only the requested output, while diagnostics go to stderr. Run adf4j <command> --help for command-specific flags.

WASM

npm install @nthings.dev/adf4j-wasm

import { loadAdf4j } from "@nthings.dev/adf4j-wasm";

const adf4j = await loadAdf4j();
const markdown = adf4j.convert(adfJsonString);
const result = adf4j.convertJson(adfJsonString);

One entry point runs in Node.js, Bun, Deno, and the browser. The npm package bundles the GraalVM Web Image loader and the compiled .wasm. In Vite, add the shipped plugin (import adf4jWasm from '@nthings.dev/adf4j-wasm/vite') or set optimizeDeps.exclude: ['@nthings.dev/adf4j-wasm']. See the package README for bundler, runtime, and self-hosting details.

Chrome extension

adf4j-chrome-ext is a local Manifest V3 extension for Confluence Cloud. It adds a floating Copy as markdown button to detected Confluence pages, fetches the published page body as atlas_doc_format, converts it with adf4j-wasm, and writes Markdown to the clipboard.

Build the unpacked extension with just chrome-ext, then load adf4j-chrome-ext/dist from chrome://extensions.

Documentation

Doc	Use it for
Getting started	Install, convert a first document, inspect results, and run the CLI.
Guide	Resolver patterns, macros, attachments, options, and AST usage.
Reference	Complete option, mapping, diagnostic, safety, CLI, and exit-code tables.
Architecture	Internal design for contributors and advanced integrators.

The local ADF spec snapshot mirrors Atlassian's format for offline reference.

Release

Releases use JReleaser and GitHub Actions. See RELEASE.md.

License

Apache-2.0.