htmltoadf

htmltoadf 是一个用 Rust 编写的 HTML 到 Atlassian 文档格式 (ADF) 转换器。

该库可以用几种不同的方式使用

• 作为命令行二进制文件（直接在兼容的主机上或使用 Docker）
• 作为 Rust 项目的库包含
• 从不同的语言或环境中调用（例如 C、JavaScript、Ruby、PHP、.NET 等）使用 FFI
• 作为 Web Assembly (wasm) 模块调用

演示

在此处查看工具作为完全在客户端运行的 WASM 库的演示：https://wouterken.github.io/htmltoadf/

命令行界面 (CLI)

二进制文件

htmltoadf 工具包含一个 html2adf 二进制文件。

用法

$ 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 从 Crates.io 安装二进制文件

$ 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`)

从 Github 下载二进制文件

预构建的二进制文件可以在此处下载： https://github.com/wouterken/htmltoadf/releases/tag/0.1.10

Docker 镜像

Docker 仓库

https://hub.docker.com/r/wouterken/html2adf

用法

$ 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"
        }
      ]
    }
  ]
}

库

示例 Rust 代码

Cargo.toml

[dependencies]
htmltoadf = "0.1.10"

代码

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

从 npm 安装软件包

import init, {convert} from "htmltoadf";
init()
  .then(() => {
    alert(convert("<h1>Hello from WebAssembly</h1>"))
  });

FFI

首先将代码编译为库，例如。

cargo build --lib --release

然后您可以从支持FFI的任何环境中动态链接到库。 非常重要，需要从发布目录复制动态库，并从FFI提供库文件的相对链接

例如：

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>")))

实现的功能

此转换器仅实现了HTML和ADF之间可能映射的子集。以下功能已实现

• 标题
• 图片
• 列表（有序和无序列表）
• 表格
• 文本和段落
• 代码
• 模糊测试
• 支持命名CSS颜色
• 智能图像大小调整
• 内联卡片
• 面板
• 表情符号
• 内置JSON Schema验证

发布流程

• 在.toml和README中递增版本号
• 编译二进制文件并创建发布
• 构建并推送Docker镜像
• 构建并推送WASM NPM包
• 推送crate
• 更新演示页面中的依赖项
• 推送到版本控制系统

测试

从存储库根目录运行 cargo test。

贡献

欢迎在GitHub上提交错误报告和拉取请求：https://github.com/wouterken/htmltoadf。该项目旨在成为一个安全、友好的协作空间，并期望贡献者遵守贡献者公约行为准则。