htmltoadf
htmltoadf is an HTML to Atlassian Document Format (ADF) converter written in Rust.
The library can be used in several different ways:
- As a command line binary (either directly on a compatible host or using Docker)
- Included as a library within a Rust project
- Called from a different language or environment (e.g. C, JavaScript, Ruby, PHP, .NET etc.) using FFI
- Called as a Web Assembly (wasm) module
Demo
See demo of the tool running as a WASM library entirely in the client here: https://wouterken.github.io/htmltoadf/
CLI
Binaries
The htmltoadf tool includes an html2adf binary.
Usage
$ html2adf -h
htmltoadf 0.1.10
An HTML to Atlassian Document Format (ADF) converter
USAGE:
html2adf [OPTIONS] [INPATH]
ARGS:
<INPATH> The path to the file to read
OPTIONS:
-h, --help Print help information
-o, --outpath <OUTPATH>
-V, --version Print version information
cargo install
Install Binary from Crates.io with $ cargo install htmltoadf
installing htmltoadf v0.1.10 (/usr/src/html2adf)
Updating crates.io index
Downloading crates ...
Downloaded lock_api v0.4.6
--snip--
Compiling htmltoadf v0.1.10
Finished release [optimized] target(s) in 1m 42s
Installing ~/.cargo/bin/htmltoadf
Installed package `htmltoadf v0.1.10` (executable `html2adf`)
Download Binary file from Github
Pre-built binaries can be downloaded from here: https://github.com/wouterken/htmltoadf/releases/tag/0.1.10
Docker Image
Docker Repo:
https://hub.docker.com/r/wouterken/html2adf
Usage
$ echo "<h1>Hello world<p>Test</p></h1>" | docker run --rm -i wouterken/html2adf:0.1.10
{"version":1,"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Hello world"},{"type":"text","text":"Test"}]}]}
$ echo "<h1>Hello world<p>Test</p></h1>" | docker run --rm -i wouterken/html2adf:0.1.10 | jq
{
"version": 1,
"type": "doc",
"content": [
{
"type": "heading",
"attrs": {
"level": 1
},
"content": [
{
"type": "text",
"text": "Hello world"
},
{
"type": "text",
"text": "Test"
}
]
}
]
}
Lib
Example Rust Code
Cargo.toml
[dependencies]
htmltoadf = "0.1.10"
Code
use htmltoadf::convert_html_str_to_adf_str;
use serde_json::json;
let converted = convert_html_str_to_adf_str("<h1>Hello World</h1>".to_string());
let expected = json!({
"version": 1,
"type": "doc",
"content": [
{
"type": "heading",
"attrs": {
"level": 1
},
"content": [
{
"type": "text",
"text": "Hello World"
}
]
}
]
}).to_string();
assert_eq!(expected, converted);
WASM
Install package from npm
import init, {convert} from "htmltoadf";
init()
.then(() => {
alert(convert("<h1>Hello from WebAssembly</h1>"))
});
FFI
First compile the code as a library, e.g.:
cargo build --lib --release
Then you can link to the library dynamic from any environment that supports a FFI. It is important to copy the dynamic library from the release directory, and provide a relative link to the library file from the FFI
E.g.
Ruby
require 'ffi'
module HTMLToADF
extend FFI::Library
ffi_lib 'libhtmltoadf'
attach_function :convert, [ :string ], :string
end
puts HTMLToADF.convert("<h1>Hello from Ruby</h1>")
Node/JavaScript
var ffi = require('ffi-napi');
var htmltoadf = ffi.Library('libhtmltoadf', {
'convert': [ 'string', [ 'string' ] ]
});
console.log(htmltoadf.convert("<h1>Hello from Node!</h1>"));
Python
from cffi import FFI
ffi = FFI()
lib = ffi.dlopen("libhtmltoadf")
ffi.cdef("char * convert(char *);")
print(ffi.string(lib.convert(b"<h1>Hello from Python!</h1>")))
Implemented features
This converter only implements a subset of possible mappings between HTML and ADF. The following features are implemented:
- [x] Headings
- [x] Images
- [x] Lists (ordered and unordered)
- [x] Tables
- [x] Text and Paragraphs
- [x] Code
- [ ] Fuzz Tests
- [ ] Support for named CSS colors
- [ ] Smart image sizing
- [ ] Inline Cards
- [ ] Panels
- [ ] Emoji
- [ ] In built JSON Schema Validation
Release Process
- Increment version number in .toml and README
- Compile binaries and create release
- Build and push Docker image
- Build and push WASM NPM package
- Push crate
- Update dependency in demo page
- Push to VCS
Testing
Run cargo test
from the repository root.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/wouterken/htmltoadf. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.