9 releases

0.1.10 Feb 18, 2024
0.1.9 Dec 22, 2023
0.1.8 Oct 10, 2023
0.1.7 Mar 12, 2023
0.1.6 Feb 11, 2022

#295 in Parser implementations

Download history 12/week @ 2024-06-08 137/week @ 2024-06-15 64/week @ 2024-06-22 122/week @ 2024-06-29 176/week @ 2024-07-06 213/week @ 2024-07-13 851/week @ 2024-07-20 306/week @ 2024-07-27 600/week @ 2024-08-03 549/week @ 2024-08-10 997/week @ 2024-08-17 675/week @ 2024-08-24 503/week @ 2024-08-31 592/week @ 2024-09-07 809/week @ 2024-09-14 1438/week @ 2024-09-21

3,488 downloads per month
Used in 2 crates

MIT license

1MB
2.5K SLoC

htmltoadf Latest Version Rustc Version 1.58+ 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

Install Binary from Crates.io with cargo install

$ 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:

  • Headings
  • Images
  • Lists (ordered and unordered)
  • Tables
  • Text and Paragraphs
  • 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.

Dependencies

~8–15MB
~188K SLoC