README.md

Note This repository is automatically generated from the main parser monorepo. Please submit any issues or pull requests there.

reoff-parse

Plugin for reoff to parse a .docx XML file into an ooxast AST. Ideally use docx-to-vfile to get to a parseable state.

Contents

• reoff-parse
  • Contents
  • What is this?
  • When should I use this?
  • Install
  • Use
  • API
    • default()
      • Signature
      • Parameters
      • Returns
    • Parsed
      • Indexable
    • RootWithSource
      • Hierarchy
      • Properties
        • children
        • data?
        • position?
        • source?
        • type
    • Settings
      • Properties
        • fragment?
        • include?
          • Default
        • leaveRaw?
          • Default
        • removeWhiteSpace?
  • Syntax tree
  • Compatibility
  • Security
  • Related
  • Contribute
  • License

What is this?

When should I use this?

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install as

pnpm add reoff-parse
# or with yarn
# yarn add reoff-parse
# or with npm
# npm install reoff-parse

Use

import { unified } from 'unified'
import { docxToVfile } from 'docx-to-vfile'
import reoffParse from 'reoff-parse'

const vfile = await docxToVfile('example.docx')

const processor = unified().use(reoffParse)

Parse the document into a tree

const tree = processor.parse(vfile)

API

---

default()

Signature

default(options: Settings = {}): void;

Parameters

Name	Type
options	Settings

Returns

void

Defined in: src/lib/reoff-parse.ts:63

---

Parsed

The parsed content of .xml files in the .docx file

Indexable

[key: XMLOrRelsString]: Root | undefined

---

RootWithSource

Hierarchy

• Root.RootWithSource

Properties

children

(Cdata | Comment | Doctype | Element | Instruction | Text)[]

Inherited from: Root.children

Defined in: node_modules/.pnpm/@[email protected]/node_modules/@types/xast/index.d.ts:58

data?

Data

Information from the ecosystem.

Inherited from: Root.data

Defined in: node_modules/.pnpm/@[email protected]/node_modules/@types/unist/index.d.ts:27

position?

Position

Location of a node in a source document. Must not be present if a node is generated.

Inherited from: Root.position

Defined in: node_modules/.pnpm/@[email protected]/node_modules/@types/unist/index.d.ts:33

source?

string

The key of the file in the VFile's data attribute. Used to identify the file in the VFile and where to put it when stringifying.

Defined in: src/lib/reoff-parse.ts:103

type

"root"

Inherited from: Root.type

Defined in: node_modules/.pnpm/@[email protected]/node_modules/@types/xast/index.d.ts:57

---

Settings

Properties

fragment?

boolean

Defined in: src/lib/reoff-parse.ts:15

include?

string[] | RegExp[] | "all" | (key: string) => boolean | "allXML"

Which files on the data attribute of the VFile to parse and turn into ooxast trees.

• allXML parses and appends all files that end with .xml.
• all parses and appends all files that end with .xml or .rels.
• if a string array is passed, it parses and appends all files that match the strings in the array.
• if a regexp array is passed, it parses and appends all files that match the regexps in the array.
• if a function is passed, it parses and appends all files that match the function.

Default

['word/footnotes.xml', 'word/endnotes.xml', 'customXml/item1.xml', 'word/glossary/document.xml']

Use of 'all' or 'allXML' is discouraged, as it will greatly increase the size of the VFile and generally be slower. You can always manually parse the files you need later. For example, if you want to find out what fonts are used in the document, you can do something like this:

import { docxToVFile } from 'docx-to-vfile'
import { fromXml } from 'xast-util-from-xml'
import { unified } from 'unified'
import { reoffParse } from 'reoff-parse'

const file = await docxToVFile(docx)

const processor = unified()
 .use(reoffParse)
 .use(() => (tree, vfile) => {
   const fontTable = fromXml(vfile.data['word/fontTable.xml'])
   // do something with the fontTable

   return tree
 })

Defined in: src/lib/reoff-parse.ts:60

leaveRaw?

boolean

Whether to leave the raw XML on the data attribute of the VFile. The raw XML is not needed in most cases, but can be useful for debugging.

By default, all XML files that match the include option are parsed and added to the data.parsed attribute of the VFile. All XML are then removed from the VFile.

Default

false

Defined in: src/lib/reoff-parse.ts:26

removeWhiteSpace?

boolean

Defined in: src/lib/reoff-parse.ts:14

Syntax tree

reoff-parse creates an [ooxast][ooxast] syntax tree, which is a subset of the [xast][xast] syntax tree specifically for Open Office XML files.

Compatibility

reoff-parse parses everything in the .docx file in a rather naive way, so most things (except for scripts) are "supported." However, by default only the footnotes, endnotes, customXML and glossary are parsed and therefore easy to use by plugins such as [reoff-unified-latex][reoff-unified-latex]. If you want to use other parts of the .docx file, such as the styles, you can use the include option to parse and add them to the VFile.

Note that all parts of the .docx file are included as a raw XML string in the VFile using the default settings of docx-to-vfile, so you can always parse them yourself using xast-util-from-xml, see the documentation of Settings above.

Security

reoff-parse does not parse scripts, but in the future it will be able to be converted into HTML using [ooxast-util-to-hast][ooxast-util-to-hast], which might allow for XSS attacks. Use [rehype-raw][rehype-raw] to be certain that no raw HTML is present in the output when converting to HTML.

Related

• xast-util-from-xml: tool used to convert XML to [xast][xast]
• docx-to-vfile: tool used to convert .docx files to VFiles which can be fed into reoff-parse

Contribute

License

GPL-3.0-or-later © Thomas F. K. Jorna