- 5.15.3Latest
- 5.15.2
- 5.15.1
- 5.15.0
- 5.14.1
- 5.14.0
- 5.13.3
- 5.13.2
- 5.13.1
- 5.13.0
- 5.12.2
- 5.12.1
- 5.12.0
- 5.11.4
- 5.11.3
- 5.11.2
- 5.11.1
- 5.11.0
- 5.10.1
- 5.10.0
- 5.9.0
- 5.8.1
- 5.8.0
- 5.7.2
- 5.7.1
- 5.7.0
- 5.6.0
- 5.5.6
- 5.5.5
- 5.5.4
- 5.5.3
- 5.5.2
- 5.5.1
- 5.5.0
- 5.4.0
- 5.3.8
- 5.3.7
- 5.3.6
- 5.3.5
- 5.3.4
- 5.3.3
- 5.3.2
- 5.3.1
- 5.3.0
- 5.2.1
- 5.2.0
- 5.1.1
- 5.1.0
- 5.0.2
- 5.0.1
- 5.0.0
- 4.0.8
- 4.0.7
- 4.0.6
- 4.0.5
- 4.0.4
- 4.0.3
- 4.0.2
- 4.0.1
- 4.0.0
- 3.2.0
- 3.1.1
- 3.1.0
- 3.0.1
- 3.0.0
- 2.4.3
- 2.4.2
- 2.4.1
- 2.2.0
- 2.1.0
- 2.0.1
- 2.0.0
- 1.6.0
- 1.5.1
- 1.5.0
- 1.4.0
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.0
- 0.0.4
- 0.0.3
- 0.0.2
- 0.0.1
DOCX Markup Language
This is a NodeJS/Deno module for making .docx
files from scratch or from
an existing DOCX/DOTX template.
You could use docxml
to:
- Create an MS Word file without ever opening MS Word
- Create a parameterized template file, and render it to DOCX with your data parameters
- Convert JSON, XML or other data structures to DOCX
- Parse content from an existing DOCX file
- Extract style definitions from a DOTX/DOCX file
docxml
can be used in NodeJS and Deno according to the traditions in those
ecosystems. For Node users, simply npm install docxml
and then require()
or import
as you wish. For Deno users,
import "deno.land/x/docxml/mod.ts"
or use an import map if you wish.
// NodeJS using CommonJS:
const { default: Docxml, Paragraph } = require('docxml');
// NodeJS using ES6 modules, or Deno with an import map
import Docxml, { Paragraph } from 'docxml';
// Deno without an import map
import Docxml, { Paragraph } from 'https://deno.land/x/docxml/mod.ts';
docxml
is designed to be used in vanilla JavaScript using class component instances, or using JSX if you’re on Deno or
want to use NodeJS and a transpiler like Babel:
const para = new Paragraph({ alignment: 'center' }, new Text({}, 'I want a cookie'));
/** @jsx Docx.jsx */
const para = (
<Paragraph alignment="center">
<Text>I want a cookie</Text>
</Paragraph>
);
👉 More on using class components
docxml
is also designed to be used from scratch/entirely programmatically, or using a more ergonomic API
to transform from an XML document. Both modes work equally well with vanilla JS or JSX.
await Docx.fromJsx(
<Paragraph alignment="center">
<Text>I want a cookie</Text>
</Paragraph>,
).toFile('example-1.docx');
await Docx.fromNothing()
.withXmlRule('self::text()', ({ node }) => <Text>{node.nodeValue}</Text>)
.withXmlRule('self::p', ({ traverse, node }) => (
<Paragraph alignment={node.getAttribute('align')}>{traverse()}</Paragraph>
))
.withXml(`<p align="center">I want a cookie</p>`, {})
.toFile('example-2.docx');
👉 Go to the API docs that Deno generates for docxml
Features
To great or small extend, the following features work in the current version of docxml
. Some items are not ticked off
yet – they are not available, but hopefully soon.
👉 See code examples of some or the more intricate features
API features:
- 100% typed
- Asynchronous components
- Component composition
Custom styles:
- Font size and color
- Bold, italic, underline styles, strike-through
- Subscript, superscript, small caps
- Paragraph spacing and indentation
- Left/right/center/justified alignment
- Numbering
- Aligning text on tabs
- Font family
- Embed TTF in the DOCX file
References:
- Cross references
- Table of contents
Tables:
- Colspans and rowspans
- Cell borders
- Table borders
- Conditional formatting
Images:
- From any
UInt8Array
source - Alternative and title text
- Width and height
Sections:
- Width and height
- Orientation
- Page headers & footers
Comments:
- Point comment
- Range comment
- Comment reply
Change tracking:
- Text additions and deletions
- Style changes
- Table row additions and deletions
Differences with actual MS Word DOCX
Obviously docxml
is a TypeScript project, which is already very different from how you would normally interact
with a DOCX document. More meaningfully however, docxml
is meant to make writing DOCX easier than going straight
to OOXML. For example;
- All sizes are of type
Length
, which means it doesn’t matter wether you input them as points, centimeters, inches, 1/2, 1/8th or 1/20th points, English Metric Units, and so on. - The JSX pragma will try to correct components that would lead to invalid XML structures, by splitting the parents of
invalidly placed components recursively until the new position is valid. Moreover, string content in unexpected places
is automatically wrapped in
<Text>
when using JSX. This makes the configuration of a new DOCX a little more forgiving. - Using the
<Image>
or<Comment>
components will automatically create all required relationships etc. - Some of the words have changed, generally speaking
docxml
is more verbose than the DOCX verbiage. - Generally speaking
docxml
prefers formal (JS) references over references-by-identifier. In those cases the identifiers are randomly generated for you when the.docx
file is written. - Especially in tables and images, a lot of formatting details are automatically applied. In a lot of cases there is no API yet to change them.
For contributors
This project uses unit tests and linting for quality control. To lint, both Deno’s own linting as well as ESLint are used. Please run both of the following commands to ensure that a GitHub Action does not fail later.
# Once
npm install
# Run all unit tests
deno task test
# Run all linting
deno task lint