beautiful-docx

Easily generate .docx files with HTML and CSS.

beautiful-docx is a wrapper around docx library that allows you to create beautiful .docx documents using HTML and CSS (inline styles) instead of JS objects.

This library is different from other available HTML to DOCX converters because of the following features (among others):

table of content generation
page numbering
custom page sizes and margins
paragraph first line indentation
automatic or manual images downloading
table and image sizing and positioning

The library is writted with TypeScript and is fully covered with unit tests.

beautiful-docx is created and maintained by Flexum. PRs are welcome. Contact us at opensource@flexum.io.

Example

Here's an example of an HTML document that allows you to generate the following file (utilizing these parameters):

Allowed HTML elements

Supported: a, article, blockquote, br, caption, col, colgroup, div, figure, h1-h6, i, img, li, ol, p, s, del, section, strong, table, tbody, td, tfoot, th, tr, u, ul, em, span, sub, sup, b, pre, aside, html, body, main, header, footer, nav

Custom elements: page-break, table-of-contents

Unsupported: abbr, address, cite, code, dd, din, dl, dt, figcaption, hr, ins, kbd, mark, picture, q, small, time

Installation

npm install beautiful-docx

Usage

Start with creating a converter instance. You may pass options object as an argument.

The converter exposes a generateDocx method that receives an HTML string and returns a buffer containing the final document.

import { DocxGenerator } from 'beautiful-docx';
import * as fs from 'fs';

const html = `
<div>
  <p>Example</p>
</div>
`;

const docxGenerator = new DocxGenerator({
  page: {
    size: {
      width: 5.5,
      height: 8,
    },
  },
});

const buffer = await docxGenerator.generateDocx(html);

fs.writeFileSync('example.docx', buffer);

Options (`docxExportOptions?: DeepPartial<DocxExportOptions>`)

Options is an object with the following fields.

`page: PageOptions`

Sets document page settings.

orientation: PageOrientation

Page orientation.

Available values: 'portrait', 'landscape'

Default: 'portrait'

Example:

import { PageOrientation } from 'beautiful-docx';

const options = {
  page: {
    orientation: PageOrientation.Portrait,
  },
};

size: PageSize

Page width and height in inches.

width: number

height: number

You can use ready-made page sizes - PageFormat

Available values: A3, A4, A5, A6;

Default: A4 (8.3’x11.7’)

Example:

import { PageFormat } from 'beautiful-docx';

const options = {
  page: {
    sizes: PageFormat.A4,
  },
};

const options = {
  page: {
    sizes: {
      width: 8.3,
      height: 11.7,
    },
  },
};

margins: object

Page margins in millimeters.

top: number

Default: 25.4
left: number

Default: 25.4
bottom: number

Default: 25.4
right: number

Default: 25.4

Example:

const options = {
  page: {
    margins: {
      top: 25,
      left: 25,
      right: 20,
      bottom: 25,
    },
  },
};

numbering: false | NumberingOptions

Responsible for displaying page numbering.
- start: number
  
  Default: 1
- type: NumberFormat
  
  Default: NumberFormat.DECIMAL
- align: AlignmentType
  
  Default: AlignmentType.CENTER
Example:
```
const options = {
  page: {
    numbering: {
      type: NumberFormat.LOWER_LETTER,
      align: AlignmentType.END,
    },
  },
};
```

`font: FontOptions`

Configuration of font sizes and font-family.

baseSize: number

Base text font size in points.

Default: 12

Example:

const options = {
  font: {
    baseSize: 11,
  },
};

headersSizes: object Header font sizes of different levels
- h1: number
  
  Default: 19.5
- h2: number
  
  Default: 16.5
- h3: number
  
  Default: 15
- h4: number
  
  Default: 13.5
- h5: number
  
  Default: 12
- h6: number
  
  Default: 10.5
Example:
```
const options = {
  font: {
    headersSizes: {
      h1: 22,
      h2: 20,
      h3: 18,
      h4: 16,
    },
  },
};
```
baseFontFamily: string

Font family for base text

Available values: any Microsoft Office Word font.

Default: 'Arial'

Example:
```
const options = {
  font: {
    baseFontFamily: 'Times New Roman',
  },
};
```
headersFontFamily: string

Font family for headers.

Available values: any Microsoft Office Word font.

Default: 'Arial'

Example:
```
const options = {
  font: {
    headersFontFamily: 'Times New Roman',
  },
};
```

`table: TableOptions`

Properties of tables.

cellPaddings: object

Table cell paddings configuration in pixels
- top: number
  
  Default: 5
- left: number
  
  Default: 5
- right: number
  
  Default: 5
- bottom: number
  
  Default: 5
Example:
```
const options = {
  table: {
    cellPaddings: {
      top: 10,
      left: 15,
    },
  },
};
```

`images: ImageMap | undefined`

The images parameter allows you to preload the images used in the html.

This is an object in which the urls of the images are the keys, and the Buffer with the image is the value.

If you do not pass the images parameter, the images will be automatically loaded from the src attributes of the img tags.

Example:

const imageSourceUrl = 'https://example.com/image.png';
const html = `
<img src="${imageSourceUrl}" />
`;

const res = await axios.get(imageSourceUrl, { responseType: 'arraybuffer' });
const imageBuffer = Buffer.from(res.data, 'binary');

const options = {
  images: {
    [imageSourceUrl]: imageBuffer,
  },
};

`verticalSpaces: number`

Vertical indents between lines ratio.

Default: 1

Example:

const options: {
  verticalSpaces: 1.15;
};

`ignoreIndentation: boolean`

If false, adds an indent for the first line of the paragraph.

Indentation is ignored for the first paragraph in a block.

Default: true

Example:

const options: {
  textIndentation: false;
};

Supported types of top-level content

The beautiful-docx library supports various types of html input content.

Plain text

Will be reformatted into a paragraph with appropriate content.

Example:

const html = 'Some plain text'; // transforms to: <p>Some plain text</p>

Inline elements

The library supports the following inline elements: 'strong', 'i', 'u', 's', 'br'.

Each inline element on the top level will be wrapped with <p>, for example:

Example:

const html = `
<strong>strong</strong>
<i>italic</i>
`;
// transforms to:
// <p><strong>strong</strong></p>
// <p><i>italic</i></p>

To avoid this you should keep inline elements within block elements.

Block elements-containers

The library allows the following container elements: 'div', 'article', 'section', 'html', 'body', 'aside', 'main', 'header', 'aside', 'footer', 'nav', 'pre'.

The library effectively ignores these elements and treats the inner content as a top-level content.

Example:

const html = `
<div>plain text</div>
<section><p>paragraph</p></section>
`;
// transforms to:
// <p>plain text</p>
// <p>paragraph</p>

Block elements

The library supports the following block elements: 'p', 'h1', 'h2', 'h3', 'h4', 'ul', 'ol', 'figure', 'blockquote', 'table', 'img'.

Block elements cannot be nested in other block elements, except for the cases provided for in the exceptions (see the description for each specific element).

Example:

const html = `
  <h1>H1 Example</h1>
  <h2>H2 Example</h2>
  <h3>H3 Example</h3>
  <h4>H4 Example</h4>
  <p>paragraph with <i>italic</i> text</p>
  <ol>
    <li>List Item</li>
    <li>List Item</li>
    <li>List Item</li>
  </ol>
`;

Custom elements

Supported custom elements: page-break, table-of-contents.

Custom elements are used to insert additional content.

Supported element specs

`div, article, section`

Container elements.

Can be nested in:

document root
other container element

Supported content:

root content

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<section>
  <article>
    <div>
      <p>Paragraph</p>
    </div>
  </article>
</section>
`;

`p`

Converts to a paragraph with text.

Can be nested in:

document root
container element
li (known issue: displayed with a new line)
blockquote
caption
td

Supported content:

plain text
inline-tags
img

Attributes: not supported

Inline-styles:

text-align - horizontal text position

Available values: justify, left, center, right

Default: left

Extra:

By default, text-indent is added for paragraphs (except the first paragraph in each block). This can be disabled by passing ignoreIndentation: true.

If necessary, you can add vertical indents between paragraphs. For this, you need to pass the parameter verticalSpaces.

Example:

const html = `
<p style='text-align: center'>Paragraph 1</p>
<p>Paragraph 2</p>
<ul>
  <li>
    <p>List item</p>
  </li>
</ul>
`;

`h1-h6`

Block elements. They are converted into headings of the appropriate level. Participate in table-of-contents formation.

Can be nested in:

document root
container element
li (partial support - displayed from a new line)
caption
td

Supported content:

plain text
inline elements
img

Attributes: not supported

Inline-styles:

text-align - horizontal text position

Available values: justify, left, center, right

Default: left

Extra:

For headings, you can set the font size and font-family. To do this, you need to pass the appropriate parameters: font.headersSizes, font.headersFontFamily.

Example:

const html = `
  <h1 style='text-align: center'>Page Title</h1>
  <h2><i>Page subtitle</i></h2>
`;

`ul, ol`

Block elements. Convert to lists.

Can be nested in:

document root
container element
li - are displayed as lower-level lists
caption
td

Supported content:

li
plain text - not recommended. Displayed from a new line as a paragraph

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<ul>
  <li>List item
      <ol>
        <li>List Item</li>
        <li>List Item</li>
        <li>List Item</li>
      </ol>
  </li>
  <li>List item</li>
<ul>
`;

`li`

Block element. Displayed as a list item.

Can be nested in:

ul

Supported content:

plain text - displayed as a list item
root content - is displayed from a new line as plain text
ul - nested list

Attributes: not supported

Inline-styles:

text-align - horizontal text position

Available values: justify, left, center, right

Default: left

Example:

const html = `
<ul>
  <li>List item
      <ol>
        <li>List Item</li>
        <li>List Item</li>
        <li>List Item</li>
      </ol>
  </li>
  <li>List item</li>
<ul>
`;

`figure`

Block element.

Can be nested in:

document root
container element
li
caption
td

Supported content:

img
table

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<figure>
  <img src='https://example.com/image.png'/>
</figure>
<figure>
  <table>
    <tbody>
      <tr>
        <td>Example</td>
      </tr>
    </tbody>
  </table>
</figure>
`;

`img`

Inline-block element. Responsible for displaying images.

Can be nested in:

document root
container element
li
caption
td
figure

Supported content: not supported

Attributes:

src

URL to download the image.

Inline-styles:

float

Necessary for horizontal image positioning. Without an attribute - the image will be located in the center of the page

Available values: left, right, center

Default: center
width

Image width. Available units - %, px, vw

If you do not specify the width, it will be automatically calculated from the initial dimensions of the image. If the width of the image is greater than the dimensions of the page - the image will be displayed on the entire width of the page.

If you set the width in % or vw - the width will be calculated based on the page size.

If you set the width in px - the width of the image will be equal to the value, but not more than the width of the page. Image height is calculated automatically based on image width and aspect ratio.

Extra:

Image orientation is calculated automatically based on file metadata.

Images for insertion can be preloaded (if they are found locally on the device or server). To do this, you need to download the image as a buffer and insert it into the images options parameter.

If a paragraph is found after the image, the image will be "linked" to this paragraph. If there is no paragraph after the image, it will be created automatically.

Example:

const url = 'https://example.com/image.png';
const html = `
<figure>
  <img src='${url}'/>
</figure>
<img style='width: 100px; float: right' src='${url}'/>
<img style='width: 50%; float: left' src='${url}'/>	
`;

`blockquote`

Block element. Displayed as italic text with left border.

Can be nested in:

document root
container element
li (partial support - displayed from a new line)
caption
td

Supported content:

plain text
root content - is displayed from a new line as plain text

Attributes: not supported

Inline-styles:

text-align - horizontal text position

Available values: justify, left, center, right

Default: left

Example:

const html = `
<blockquote>
  Premature Optimization Is the Root of All Evil
<blockquote>
`;

`table`

Block element. Responsible for displaying tables.

Can be nested in:

document root
container element
li
td
figure

Supported content:

thead
tr
tfoot
tr
colgroup
caption

Attributes: not supported

Inline-styles:

width

Supported units: %, px, pt, vw, auto, em, rem

Without the attribute or with auto value - the table will stretch to the entire width of the page

vh value ignored.

em, rem sets table width relative to options.font.baseSize value

Example:

const html = `
<table>
  <caption>Table</caption>
  <colgroup>
    <col style="width:30%;">
    <col style="width:70%;">
  </colgroup>
  <tbody>
    <tr>
  	  <td>First</td>
  	  <td>Second</td>
    </tr>
    <tr>
  	  <td>First</td>
  	  <td>Second</td>
    </tr>
  </tbody>
</table>
`;

`caption`

Block element. Responsible for displaying the table header.

Can be nested in:

table

Supported content:

root-content (except table)

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <caption>Table</caption>
  <tbody>
    <tr>
      <td>Cell</td>
    </tr>
  </tbody>
</table>
`;

`thead`

Responsible for displaying rows of the table with a header.

Can be nested in:

table

Supported content:

tr

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <thead>
    <tr>
      <td>Cell</td>
    </tr>
  </thead>
</table>
`;

`tbody`

Responsible for displaying the body of the table.

Can be nested in:

table

Supported content:

tr

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <tbody>
    <tr>
      <td>Cell</td>
    </tr>
  </tbody>
</table>
`;

`tfoot`

Responsible for displaying the footer of the table.

Can be nested in:

table

Supported content:

tr

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <tfoot>
    <tr>
      <td>Cell</td>
    </tr>
  </tfoot>
</table>
`;

`tr`

Responsible for displaying table rows.

Can be nested in:

table
tbody
thead
tfoot

Supported content:

td
th

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <tbody>
    <tr>
      <td>Cell</td>
    </tr>
  </tbody>
</table>
`;

`colgroup`

Responsible for setting column widths and styles for those columns.

Can be nested in:

table

Supported content:

col

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table>
  <colgroup>
    <col style="width:30%;">
    <col style="width:70%;">
  </colgroup>
  <tbody>
    <tr>
      <td>First</td>
      <td>Second</td>
    </tr>
    <tr>
      <td>First</td>
      <td>Second</td>
    </tr>
  </tbody>
</table>
`;

`td, th`

Responsible for table cells and their display.

Can be nested in:

tbody
tr
thead
tfoot

Supported content:

root content

Attributes:

rowspan, colspan

To merge cells into one horizontally and vertically.

Default: 1

Inline-styles:

background-color

Cell background.

Default: transparent

If the cell is inside thead - default background will be - #F2F2F2
border

Sets the table cell border.

Format: {widht} {style} {color}

Default: 4px solid #bfbfbf
border-width

Default: 4px
border-color

Default: #bfbfbf
border-style

Default: solid

The border-width, border-color, border-style styles are more specific and overwrite the border value if it is passed.

vertical-align

Vertical content positioning

Available values: top, bottom, center

Default: center
padding

Internal cell indents

Format:
- {top} {right} {bottom} {left}
- {top} {left, right} {bottom}
- {top, bottom} {left, right}
- {top, left, right, bottom}
Default value: 5px
padding-left, padding-right, padding-top, padding-bottom

Indent accordingly for each side of the cell.

Default: 5px

Also, the internal indents of the table cells can be set for the entire table through the options parameter table.cellPaddings.

Values written through the style property have greater specificity than values passed through parameters and are overwritten accordingly.

Values specific to each side of the cell have greater specificity than padding values and are overwritten accordingly.

Example:

const html = `
<table>
  <colgroup>
    <col style="width:30%;">
    <col style="width:70%;">
  </colgroup>
  <tbody>
    <tr>
      <td style="border: 5px solid #000; padding: 10px">First</td>
      <td rowspan="2">Second</td>
    </tr>
    <tr>
      <td>First</td>
    </tr>
  </tbody>
</table>
`;

`col`

Responsible for setting the width of the column.

Can be nested in:

colgroup

Supported content: not supported

Attributes: not supported

Inline-styles:

width

Responsible for the width of the table columns. Supported units: %, px, pt, vw, auto, em, rem

Without the attribute or with auto value - the size of the column will be automatically calculated from the width of the table and the number of columns.

vh value ignored.

em, rem sets table columns width relative to options.font.baseSize value

If the number of col does not correspond to the number of columns - the size of the columns will be automatically calculated from the width of the table and the number of columns

Example:

const html = `
<table>
  <colgroup>
    <col style="width:30%;">
    <col style="width:70%;">
  </colgroup>
  <tbody>
    <tr>
      <td>First</td>
      <td>Second</td>
    </tr>
    <tr>
      <td>First</td>
      <td>Second</td>
    </tr>
  </tbody>
</table>
`;

`br`

Inline element. Adds a line break.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

When present in the root of the document or container elements, it add line break to previous paragraph

Supported content: not supported

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<p>some text <br/> new line<p>
`;

`strong`, `b`

Inline element. Makes the text bold.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <strong>strong</strong><p>
`;

`i`, `em`

Inline element. Makes the text italic.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <i>italic</i><p>
`;

`u`

Inline element. Makes the text underlined.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <u>underlined</u><p>
`;

`s`

Inline element. Makes the text crossed out.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <s>strikethrough</s><p>
`;

`del`

Inline element. Makes the text crossed out.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <del>strikethrough</del><p>
`;

`span`

Inline element. Contains other inline elements.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <span>another text</span><p>
`;

`sub`

Inline element. Defines subscript text.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <sub>subscripted text</sub><p>
`;

`sup`

Inline element. Defines superscript text.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes: not supported

Inline-styles:

color
background-color

Example:

const html = `
<p>some text <sup>superscripted text</sup><p>
`;

`a`

Inline element. Inserts a link.

Can be nested in:

document root
container element
li
blockquote
caption
td
p
h1-h6

If there are containers in the root of the document or tags - it is wrapped in a paragraph, which is why it is displayed from a new line.

Supported content:

plain text
inline-tags

Attributes:

href

The URL of the page that should open when clicked.

Inline-styles: not supported

Example:

const html = `
<p>some text <a href='https://example.com'>example.com</a><p>
`;

`page-break`

Adds a page break.

Can be nested in:

document root
container element
li
blockquote
caption
td

Supported content: not supported

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<p>Page 1</p>
<page-break/>
<p>Page 2</p>
`;

`table-of-contents`

Adds a table of contents to the document, automatically generated based on the headings.

Can be nested in:

document root
container element
li
blockquote
caption
td

Supported content: not supported

Attributes: not supported

Inline-styles: not supported

Example:

const html = `
<table-of-contents/>
<h1>H1 Example</h1>
<h2>H2 Example</h2>
<h3>H3 Example</h3>
<h4>H4 Example</h4>
`;

Contributors

(Made with contrib.rocks)

Name		Name	Last commit message	Last commit date
Latest commit History 217 Commits
.husky		.husky
.vscode		.vscode
example		example
lib/cjs		lib/cjs
logo		logo
src		src
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.json		tsconfig.json

flexumio/beautiful-docx

Folders and files

Latest commit

History

Repository files navigation

beautiful-docx

Example

Table of Contents

Allowed HTML elements

Installation

Usage

Options (docxExportOptions?: DeepPartial<DocxExportOptions>)

page: PageOptions

font: FontOptions

table: TableOptions

images: ImageMap | undefined

verticalSpaces: number

ignoreIndentation: boolean

Supported types of top-level content

Plain text

Inline elements

Block elements-containers

Block elements

Custom elements

Supported element specs

div, article, section

p

h1-h6

ul, ol

li

figure

img

blockquote

table

caption

thead

tbody

tfoot

tr

colgroup

td, th

col

br

strong, b

i, em

u

s

del

span

sub

sup

a

page-break

table-of-contents

Contributors

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 6

Languages

Options (`docxExportOptions?: DeepPartial<DocxExportOptions>`)

`page: PageOptions`

`font: FontOptions`

`table: TableOptions`

`images: ImageMap | undefined`

`verticalSpaces: number`

`ignoreIndentation: boolean`

`div, article, section`

`p`

`h1-h6`

`ul, ol`

`li`

`figure`

`img`

`blockquote`

`table`

`caption`

`thead`

`tbody`

`tfoot`

`tr`

`colgroup`

`td, th`

`col`

`br`

`strong`, `b`

`i`, `em`

`u`

`s`

`del`

`span`

`sub`

`sup`

`a`

`page-break`

`table-of-contents`

Packages