# docxmarks

> Super simple bookmark replacement / mail merge for docx files

Latest version **2.3.0** (published 2024-04-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install docxmarks
pnpm add docxmarks
yarn add docxmarks
bun add docxmarks
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2024-04-24 |
| First published | 2015-09-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.0.0 |
| Dependencies | 1 |
| Unpacked size | 8.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Andrew Carpenter |
| Maintainers | doesdev |
| Keywords | docx, ooxml, mail merge, replace, bookmark, bookmarks, word, microsoft word, libre office, libre writer, open office |

## Links

- npm: https://www.npmjs.com/package/docxmarks
- Repository: https://github.com/musocrat/docxmarks
- Homepage: http://docxmarks.doesdev.com
- Issues: https://github.com/musocrat/docxmarks/issues
- npm.io page: https://npm.io/package/docxmarks

## Dependencies (1)

- [jszip](https://npm.io/package/jszip.md) ^3.10.1

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 2.3.0 (latest) — 2024-04-24
- 2.2.4 — 2019-07-15
- 2.2.3 — 2019-06-01
- 2.2.2 — 2018-08-10
- 2.2.1 — 2017-10-01
- 2.2.0 — 2017-08-28
- 2.1.1 — 2017-08-28
- 2.1.0 — 2017-08-13
- 2.0.1 — 2017-08-13
- 2.0.0 — 2017-08-13
- 1.0.0 — 2015-09-13

## README

# docxmarks   [![npm version](https://badge.fury.io/js/docxmarks.svg)](http://badge.fury.io/js/docxmarks)   [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)   [![Dependency Status](https://dependencyci.com/github/doesdev/docxmarks/badge)](https://dependencyci.com/github/doesdev/docxmarks)

Replace text in native bookmarks in Open XML Document Files (.docx).

Formatting will follow the initial style inside the bookmark. That is to say,
if you have content inside the bookmark the first character defines the styling.
This is the same behavior supplied in Microsoft Word's libraries.

This library will also only handle text, nothing else.

I say all of that to say if you need more advanced formatting and content
options then you should be using
[docxtemplater](https://github.com/open-xml-templating/docxtemplater).

## Install
`npm i docxmarks --save`

## Usage

```javascript
const docxmarks = require('docxmarks')
const fs = require('fs')
const docx = fs.readFileSync('path/to/document.docx')

const replacements = {
  first: 'Andrew',
  last: (val) => val || 'Carpenter',
  maybeNoBookmark: {append: true, setter: 'There is one now'}
}
docxmarks(docx, replacements).then((data) => {
  fs.writeFileSync('path/to/newDocument.docx', data)
})
```

## API

#### Takes docx data, replaces bookmarks, returns `Promise` resolving with new docx data in the same encoding as provided in input.

** omitting `replacements` will resolve with an object describing bookmarks currently in the document*

#### `docxmarks(*docxData, *replacements)`

- **docxData** *[base64 | Buffer | ArrayBuffer | Uint8Array - required]*
- **replacements** *[object - optional]*
  - **key** - Name of bookmark to replace, is case sensitive
  - **value** *[string | function | object]* - Bookmark replacement value
    - **string** - Replace bookmark with string's value
    - **function** - Receives current text of bookmark, bookmark set with return value
    - **object** - {`*setter`, `*append`}
      - **setter** *[string | function - required]* same as string / function above
      - **append** *[boolean - optional - false]* if bookmark not found append to document


## Upgrading

Version 2.0.0 is a complete re-write with 100% different API. Use new API if
upgrading from an old version, as there is no transitional API.


## License

MIT © [Andrew Carpenter](https://github.com/doesdev)

---
_Source: https://npm.io/package/docxmarks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._