The LitAST node model

LitAST is a tree of plain JSON objects. You can save it with JSON.stringify and later hand the JSON.parse result to generateDocx.

Common fields

Any node may carry these fields:

parseDocx returns mutable LitNodes; generateDocx accepts read-only LitAstNodes. Both have the same structure.

Attributes starting with an underscore (such as _pPrPreservation) are internal data kept for writing the original file back. Ignore them when reading; keep them when editing so the original formatting is written back intact.

An example

A paragraph with bold text:

{
  "type": "document",
  "attrs": { "version": 1 },
  "children": [
    {
      "type": "paragraph",
      "children": [
        { "type": "text", "text": "Hello " },
        { "type": "text", "text": "world", "marks": [{ "type": "bold" }] }
      ]
    }
  ]
}

Node types

Mark types

bold, italic, underline, strike, doubleStrike, superscript, subscript, code, link, highlight, textStyle, plus insertion / deletion for tracked changes.

Font size, color, font family and similar properties live in the attrs of a textStyle mark, for example:

{ "type": "textStyle", "attrs": { "fontSize": "14pt", "color": "#C00000" } }

Paragraphs and headings

Paragraph formatting lives in attrs, for example textAlign, spacing and indent. A heading stores its level (1–6) in attrs.level.

Lists

Lists are list > listItem, with list.attrs.ordered telling ordered from unordered. Each listItem is one numbered paragraph and holds inline nodes (text, field and so on) directly, without a wrapping paragraph. An item's depth is listItem.attrs.level, starting at 0. Items at different levels or with different numbering definitions are split into adjacent list nodes rather than nesting a list inside a listItem:

list {"ordered":true}
  listItem {"level":0} > text "one"
list {"ordered":false}
  listItem {"level":1} > text "nested"
list {"ordered":true}
  listItem {"level":0} > text "two"

Pass numberingMode: "flat-numbered-paragraphs" when parsing to keep Word's flat numbered paragraphs instead.

Use the same shape when generating. Do not put block nodes such as paragraph or list inside a listItem; that produces invalid nested paragraphs.

Phonetic guides

ruby is an inline node: children holds the annotated base text and attrs.rubyText holds the annotation. Both are arrays of inline nodes with their own text formatting. The other attrs are Word's guide properties: rubyAlign, hps (annotation size), hpsRaise (raise), hpsBaseText (reference base size), lid (language) and dirty; sizes and distances are in half-points:

ruby {"rubyAlign":"center","hps":12,"hpsRaise":24,"hpsBaseText":24,"lid":"zh-CN","rubyText":[text "hàn"]}
  text "汉"

lit-docx never infers pronunciation; it reads and writes the annotation stored in the file. See Generating DOCX to create one.

Sections

A section is not a container around content but a sibling in document.children: it ends the section formed by the content before it and carries that section's page setup. Every Word document ends with at least one section:

{
  "type": "section",
  "attrs": {
    "pageWidth": 11906, "pageHeight": 16838, "orientation": "portrait", "paperSize": "A4",
    "margins": { "top": 1440, "right": 1440, "bottom": 1440, "left": 1440, "header": 708, "footer": 708, "gutter": 0 }
  },
  "children": []
}

The section's headers and footers are its header / footer children. For units, see Generating DOCX.

Document metadata

The root's meta holds package-level data that is not body content. Common keys:

A key appears only when the document actually contains that data.