README
U
BreakType
U
Comment
U
ConversionResult
U
DocumentElement
U
DocumentMatcher
U
DocxPackageResult
U
DocxReadResult
U
DocxXmlResourceLimit
U
HtmlNode
U
HtmlPathElement
U
Image
U
ImageConversion
U
Indent
U
Message
U
Note
U
Numbering
U
OutputFormat
U
ParagraphProperties
U
RunProperties
U
StyleMapParseResult
U
StyleMapping
U
StyleNameMatcher
U
TableProperties
U
VerticalAlignment
U
XmlElement
U
XmlNode
U
ZipArchive
- ::equalDocxError::equal
- ::not_equalDocxError::not_equal
- ::to_reprDocxError::to_repr
V
bookmark_start
V
checkbox
V
column_break
V
combine_results
V
comment
V
comment_reference
V
comment_reply
V
comment_spec
V
convert
V
convert_document
V
convert_document_to_html
V
convert_document_to_markdown
V
convert_to_html
V
convert_to_markdown
V
data_uri_image
V
data_uri_image_converter
V
default_style_map_lines
V
document
V
document_descendants
V
document_descendants_where
V
embed_style_map
V
error
V
escape_html
V
escape_html_attribute
V
escape_markdown_text
V
extract_raw_text
V
extract_raw_text_from_document
V
fresh_html_element
V
header_footer_spec
V
html_element
V
html_text
V
hyperlink
V
identity_document_transform
V
image
V
image_conversion
V
img_element
V
indent
V
inline_image
V
join_zip_path
V
line_break
V
new_blank_docx
V
note
V
note_reference
V
note_spec
V
numbering
V
open_zip
V
page_break
V
paragraph
V
paragraph_properties
V
parse_style_map
V
parse_style_map_string
V
read_docx
V
read_docx_annotated
V
read_docx_package
V
read_docx_with_messages
V
read_embedded_style_map
V
read_style_map
V
read_style_map_string
V
read_style_mapping
V
read_xml_string
V
run
V
run_properties
V
simplify_html
V
split_zip_path
V
success
V
tab
V
table
V
table_cell
V
table_properties
V
table_row
V
text
V
transform_elements
V
transform_paragraphs
V
transform_runs
V
warning
V
write_docx
V
write_docx_with_annotations
V
write_docx_with_comments
V
write_html
V
write_markdown
V
write_xml_string
V
xml_element
V
xml_text
V
zip_archive

docx2html

Native MoonBit DOCX to HTML/Markdown converter ported from Mammoth

docx

html

markdown

mammoth

Download zip

Author

bobzhang

Version

0.5.0

License

Apache-2.0

Repository

github.com/bobzhang/docx2html

Last updated

11 hours ago

Downloads

468

Dependencies

#bobzhang/docx2html

Native MoonBit DOCX reader and converter, ported from Mammoth. The current focus is the common docx -> html, docx -> markdown, and raw-text paths with Mammoth-compatible diagnostics where the JavaScript library exposes them.

#Install

moon add bobzhang/docx2html

#Usage

///|
test "convert document model to html" {
  let doc = @docx2html.document([
    @docx2html.paragraph([@docx2html.text("Hello.")]),
  ])
  let result = @docx2html.convert_document_to_html(doc)
  inspect(result.value, content="<p>Hello.</p>")
}

Use convert or convert_document with output_format=Markdown when the format is chosen dynamically:

///|
test "choose markdown output" {
  let doc = @docx2html.document([
    @docx2html.paragraph([@docx2html.text("Hello.")]),
  ])
  let result = @docx2html.convert_document(doc, output_format=Markdown)
  inspect(result.value, content="Hello\\.\n\n")
}

For DOCX bytes, use convert, convert_to_html, convert_to_markdown, or extract_raw_text. The native API accepts BytesView, so callers can decide how to load files. External linked images stay disabled by default, matching Mammoth; pass external_file_access=true and a read_external_file callback when the source document is allowed to read sibling files. Use read_docx_with_messages when you need the parsed document model together with DOCX reader diagnostics; read_docx is the document-only convenience wrapper.

#Style Maps

Pass explicit style-map lines with style_map. If you already have a Mammoth-style multi-line string, normalize it with read_style_map_string so comments, blank lines, and trimming follow Mammoth's option parser:

///|
test "parse mammoth style map strings" {
  let style_map_text =
    #|# ignored
    #|
    #|p[style-name='Heading 1'] => h2
  let style_map = @docx2html.read_style_map_string(style_map_text)
  let doc = @docx2html.document([
    @docx2html.paragraph(
      [@docx2html.text("Title")],
      properties=@docx2html.paragraph_properties(style_name=Some("Heading 1")),
    ),
  ])
  let result = @docx2html.convert_document_to_html(doc, style_map~)
  inspect(result.value, content="<h2>Title</h2>")
}

Use parse_style_map or parse_style_map_string when you want to validate a style map before conversion while preserving the valid mappings:

///|
test "preflight style map diagnostics" {
  let parsed = @docx2html.parse_style_map_string(
    "p.SectionTitle => h2\np => span#",
  )
  inspect(parsed.mappings.length(), content="1")
  debug_inspect(
    parsed.messages,
    content=(
      #|[Warning("Did not understand this style mapping, so ignored it: p => span#\nError was at character number 10: Expected end but got unrecognisedCharacter \"#\"")]
    ),
  )
}

#Document Model

The document model exposes enum constructors for pattern matching and lower-snake helpers for building nodes and property records:

///|
test "build document model with helpers" {
  let doc = @docx2html.document([
    @docx2html.paragraph(
      [
        @docx2html.hyperlink(
          [@docx2html.text("MoonBit")],
          href=Some("https://www.moonbitlang.com"),
        ),
      ],
      properties=@docx2html.paragraph_properties(style_name=Some("Heading 1")),
    ),
    @docx2html.table([
      @docx2html.table_row([
        @docx2html.table_cell([@docx2html.paragraph([@docx2html.text("Cell")])]),
      ]),
    ]),
  ])
  let result = @docx2html.convert_document_to_html(doc, style_map=[
    "p[style-name='Heading 1'] => h2",
  ])
  inspect(
    result.value,
    content="<h2><a href=\"https://www.moonbitlang.com\">MoonBit</a></h2><table><tr><td><p>Cell</p></td></tr></table>",
  )
}

Embedded style maps can be inspected or rewritten without a JavaScript-style mutable ZIP object. Use read_embedded_style_map(docx) to read the raw mammoth/style-map part, and embed_style_map(docx, "p => h1") to return a new DOCX archive with the style map, relationship entry, and content-type override updated.

#Transforms

Document transforms run before conversion and recurse through child-bearing nodes. Use the typed helpers instead of Mammoth's JavaScript string type names:

///|
test "transform runs before conversion" {
  let doc = @docx2html.document([
    @docx2html.paragraph([@docx2html.run([@docx2html.text("Hello.")])]),
  ])
  let transform_document = @docx2html.transform_runs(fn(_run) {
    @docx2html.run([@docx2html.text("Goodbye.")])
  })
  let result = @docx2html.convert_document_to_html(doc, transform_document~)
  inspect(result.value, content="<p>Goodbye.</p>")
  let runs = @docx2html.document_descendants_where(doc, fn(element) {
    element is Run(..)
  })
  inspect(runs.length(), content="1")
}

#Native CLI

From this repository checkout, the native executable mirrors the common Mammoth CLI paths:

moon run --target native cmd/docx2html -- input.docx
moon run --target native cmd/docx2html -- --output-format=markdown input.docx
moon run --target native cmd/docx2html -- --style-map style-map input.docx output.html
moon run --target native cmd/docx2html -- --output-dir out input.docx

The executable examples in tests/cram/cli.md are verified by:

moon cram test tests/cram

#Image Conversion

Images are emitted as data URIs by default. Pass convert_image to override that behavior. data_uri_image is the default converter, and inline_image is the MoonBit name for Mammoth's images.inline/images.imgElement helper:

///|
test "custom image conversion" {
  let image = @docx2html.Image::{
    content_type: "image/png",
    alt_text: Some("chart"),
    data: b"abc",
  }
  let doc = @docx2html.document([@docx2html.paragraph([Image(image)])])
  let convert_image = @docx2html.inline_image(fn(_image) {
    { "src": "/assets/chart.png" }
  })
  let result = @docx2html.convert_document_to_html(doc, convert_image~)
  inspect(
    result.value,
    content="<p><img alt=\"chart\" src=\"/assets/chart.png\" /></p>",
  )
}

Image converters return diagnostics explicitly instead of throwing:

///|
test "custom image conversion diagnostics" {
  let image = @docx2html.image("image/png", b"abc", alt_text=Some("chart"))
  let convert_image = fn(_image : @docx2html.Image) {
    @docx2html.image_conversion([], messages=[@docx2html.error("image omitted")])
  }
  let result = @docx2html.convert_document_to_html(image, convert_image~)
  inspect(result.value, content="")
  debug_inspect(result.messages, content="[Error(\"image omitted\")]")
}

#Results

Conversion results carry rendered text plus diagnostics. Use combine_results when stitching several conversion fragments together:

///|
test "combine conversion results" {
  let combined = @docx2html.combine_results([
    @docx2html.success("One"),
    { value: "Two", messages: [Warning("same")], },
    { value: "Three", messages: [Warning("same")], },
  ])
  inspect(combined.value, content="OneTwoThree")
  debug_inspect(combined.messages, content="[Warning(\"same\")]")
}

#Status

This is an active native-first port. The verified scope covers the core docx -> html, docx -> markdown, and raw-text paths, plus embedded style maps, external-image loader callbacks, notes, comments, tables, hyperlinks, complex fields, XML/ZIP helpers, and the native CLI. See MammothParity.md for the current parity ledger, StressTesting.md for large-file comparison notes, and the intentional API differences from Mammoth's JavaScript surface.

docx2html

#bobzhang/docx2html

#Install

#Usage

#Style Maps

#Document Model

#Transforms

#Native CLI

#Image Conversion

#Results

#Status

#BreakType

#Comment

#ConversionResult

#DocumentElement

#DocumentMatcher

#DocxPackageResult

#DocxReadResult

#DocxXmlResourceLimit

#HtmlNode

#HtmlPathElement

#Image

#ImageConversion

#Indent

#Message

#Note

#Numbering

#OutputFormat

#ParagraphProperties

#RunProperties

#StyleMapParseResult

#StyleMapping

#StyleNameMatcher

#TableProperties

#VerticalAlignment

#XmlElement

#XmlNode

#ZipArchive

#DocxError

#DocxError::equal

#DocxError::not_equal

#DocxError::to_repr

#bookmark_start

#checkbox

#column_break

#combine_results

#comment

#comment_reference

#comment_reply

#comment_spec

#convert

#convert_document

#convert_document_to_html

#convert_document_to_markdown

#convert_to_html

#convert_to_markdown

#data_uri_image

#data_uri_image_converter

#default_style_map_lines

#document

#document_descendants

#document_descendants_where

#embed_style_map

#error

#escape_html

#escape_html_attribute

#escape_markdown_text

#extract_raw_text

#extract_raw_text_from_document

#fresh_html_element

#header_footer_spec

#html_element

#html_text

#hyperlink

#identity_document_transform

#image

#image_conversion

#img_element

#indent

#inline_image

BreakType

Comment

ConversionResult

DocumentElement

DocumentMatcher

DocxPackageResult

DocxReadResult

DocxXmlResourceLimit

HtmlNode

HtmlPathElement

Image

ImageConversion

Indent

Message

Note

Numbering

OutputFormat

ParagraphProperties

RunProperties

StyleMapParseResult

StyleMapping

StyleNameMatcher

TableProperties

VerticalAlignment

XmlElement

XmlNode

ZipArchive

DocxError

DocxError::equal

DocxError::not_equal

DocxError::to_repr

bookmark_start

checkbox

column_break

combine_results

comment

comment_reference

comment_reply

comment_spec

convert

convert_document

convert_document_to_html

convert_document_to_markdown

convert_to_html

convert_to_markdown

data_uri_image

data_uri_image_converter

default_style_map_lines

document

document_descendants

document_descendants_where

embed_style_map

error

escape_html

escape_html_attribute

escape_markdown_text

extract_raw_text

extract_raw_text_from_document

fresh_html_element

header_footer_spec

html_element

html_text

hyperlink

identity_document_transform

image

image_conversion

img_element

indent

inline_image

join_zip_path

line_break

new_blank_docx

note

note_reference

note_spec

numbering

open_zip

page_break

paragraph

paragraph_properties