0
# Style Map Management
1
2
Functions for embedding and reading custom style maps in DOCX documents.
3
4
## embedStyleMap
5
6
Embed a style map into a DOCX file, creating a new DOCX file with the embedded style map that will be automatically used when the document is processed by Mammoth.
7
8
```javascript { .api }
9
function embedStyleMap(input: Input, styleMap: string): Promise<{
10
toArrayBuffer: () => ArrayBuffer;
11
toBuffer: () => Buffer;
12
}>;
13
```
14
15
### Parameters
16
17
- `input`: Document input
18
- `{path: string}` - Path to the .docx file (Node.js)
19
- `{buffer: Buffer}` - Buffer containing .docx file (Node.js)
20
- `{arrayBuffer: ArrayBuffer}` - ArrayBuffer containing .docx file (Browser)
21
22
- `styleMap`: Style map string containing the mapping rules
23
24
### Returns
25
26
Promise resolving to an object with methods to access the new document:
27
- `toArrayBuffer()`: Get the new document as an ArrayBuffer
28
- `toBuffer()`: Get the new document as a Buffer (Node.js only)
29
30
### Usage Examples
31
32
#### Embed Style Map and Save File
33
34
```javascript
35
const mammoth = require("mammoth");
36
const fs = require("fs");
37
38
const styleMap = `
39
p[style-name='Section Title'] => h1:fresh
40
p[style-name='Subsection Title'] => h2:fresh
41
p[style-name='Code Block'] => pre
42
r[style-name='Code'] => code
43
`;
44
45
mammoth.embedStyleMap({path: "source.docx"}, styleMap)
46
.then(function(docx) {
47
return new Promise(function(resolve, reject) {
48
fs.writeFile("output-with-styles.docx", docx.toBuffer(), function(err) {
49
if (err) reject(err);
50
else resolve();
51
});
52
});
53
})
54
.then(function() {
55
console.log("Style map embedded successfully");
56
});
57
```
58
59
#### Browser Usage with ArrayBuffer
60
61
```javascript
62
// In browser environment
63
function embedStylesInBrowser(fileArrayBuffer) {
64
const styleMap = "p[style-name='Title'] => h1:fresh";
65
66
return mammoth.embedStyleMap({arrayBuffer: fileArrayBuffer}, styleMap)
67
.then(function(docx) {
68
const newArrayBuffer = docx.toArrayBuffer();
69
70
// Create download link
71
const blob = new Blob([newArrayBuffer], {
72
type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
73
});
74
75
const url = URL.createObjectURL(blob);
76
const a = document.createElement('a');
77
a.href = url;
78
a.download = 'document-with-styles.docx';
79
a.click();
80
});
81
}
82
```
83
84
## readEmbeddedStyleMap
85
86
Read the embedded style map from a DOCX document that was previously created with `embedStyleMap`.
87
88
```javascript { .api }
89
function readEmbeddedStyleMap(input: Input): Promise<string>;
90
```
91
92
### Parameters
93
94
- `input`: Document input (same format as other mammoth functions)
95
96
### Returns
97
98
Promise resolving to a string containing the embedded style map, or empty string if no embedded style map is found.
99
100
### Usage Example
101
102
```javascript
103
const mammoth = require("mammoth");
104
105
mammoth.readEmbeddedStyleMap({path: "document-with-styles.docx"})
106
.then(function(styleMap) {
107
if (styleMap) {
108
console.log("Found embedded style map:");
109
console.log(styleMap);
110
} else {
111
console.log("No embedded style map found");
112
}
113
});
114
```
115
116
## Workflow Example
117
118
Complete workflow showing how to create a document with embedded styles and then use it:
119
120
```javascript
121
const mammoth = require("mammoth");
122
const fs = require("fs");
123
124
// Step 1: Define custom style map
125
const customStyleMap = `
126
# Custom styles for corporate documents
127
p[style-name='Corporate Header'] => h1.corporate-header
128
p[style-name='Section Header'] => h2.section-header
129
p[style-name='Highlight Box'] => div.highlight-box > p:fresh
130
r[style-name='Brand Name'] => span.brand-name
131
r[style-name='Important'] => strong.important
132
`;
133
134
// Step 2: Embed style map into document
135
function createStyledDocument() {
136
return mammoth.embedStyleMap({path: "template.docx"}, customStyleMap)
137
.then(function(docx) {
138
return new Promise(function(resolve, reject) {
139
fs.writeFile("styled-template.docx", docx.toBuffer(), function(err) {
140
if (err) reject(err);
141
else resolve("styled-template.docx");
142
});
143
});
144
});
145
}
146
147
// Step 3: Use document with embedded styles
148
function convertStyledDocument(filePath) {
149
// The embedded style map will be automatically used
150
return mammoth.convertToHtml({path: filePath})
151
.then(function(result) {
152
console.log("Converted with embedded styles:");
153
console.log(result.value);
154
return result;
155
});
156
}
157
158
// Step 4: Verify embedded styles
159
function verifyEmbeddedStyles(filePath) {
160
return mammoth.readEmbeddedStyleMap({path: filePath})
161
.then(function(styleMap) {
162
console.log("Embedded style map:");
163
console.log(styleMap);
164
return styleMap;
165
});
166
}
167
168
// Complete workflow
169
createStyledDocument()
170
.then(convertStyledDocument)
171
.then(() => verifyEmbeddedStyles("styled-template.docx"))
172
.catch(console.error);
173
```
174
175
## Style Map Format
176
177
The style map string uses the same format as the `styleMap` option in conversion functions:
178
179
### Basic Syntax
180
181
```javascript
182
const styleMap = `
183
p[style-name='Heading 1'] => h1
184
p[style-name='Heading 2'] => h2
185
r[style-name='Code'] => code
186
b => strong
187
i => em
188
`;
189
```
190
191
### Advanced Features
192
193
```javascript
194
const advancedStyleMap = `
195
# Comments start with #
196
# This is ignored
197
198
# Paragraph styles
199
p[style-name='Title'] => h1:fresh
200
p[style-name='Subtitle'] => h2.subtitle:fresh
201
202
# Character styles
203
r[style-name='Highlight'] => span.highlight
204
r[style-name='Code'] => code
205
206
# Text formatting overrides
207
b => strong
208
i => em
209
u => span.underline
210
strike => del
211
212
# Special selectors
213
p:unordered-list(1) => ul > li:fresh
214
p:ordered-list(1) => ol > li:fresh
215
`;
216
```
217
218
## Integration with Conversion Options
219
220
Embedded style maps work alongside conversion options:
221
222
```javascript
223
// The embedded style map will be combined with these options
224
const options = {
225
includeEmbeddedStyleMap: true, // Include embedded styles (default)
226
includeDefaultStyleMap: true, // Include default mappings (default)
227
styleMap: [ // Additional style mappings
228
"p[style-name='Special'] => div.special"
229
]
230
};
231
232
mammoth.convertToHtml({path: "styled-document.docx"}, options);
233
```
234
235
### Style Map Priority
236
237
Style maps are applied in this order (highest to lowest priority):
238
239
1. `options.styleMap` - Style mappings passed to conversion functions
240
2. Embedded style map - Style map embedded in the document
241
3. Default style map - Mammoth's built-in style mappings
242
243
### Disabling Embedded Styles
244
245
```javascript
246
// Ignore embedded style map
247
const options = {
248
includeEmbeddedStyleMap: false
249
};
250
251
mammoth.convertToHtml({path: "document.docx"}, options);
252
```
253
254
## Error Handling
255
256
```javascript
257
mammoth.embedStyleMap({path: "nonexistent.docx"}, "p => h1")
258
.catch(function(error) {
259
console.error("Failed to embed style map:", error.message);
260
});
261
262
mammoth.readEmbeddedStyleMap({path: "document.docx"})
263
.then(function(styleMap) {
264
if (!styleMap) {
265
console.log("No embedded style map found");
266
}
267
})
268
.catch(function(error) {
269
console.error("Failed to read embedded style map:", error.message);
270
});
271
```