0
# Style Utilities
1
2
Utilities for handling underline and other styling elements in document conversion.
3
4
## underline.element
5
6
Create underline element with specified HTML tag name.
7
8
```javascript { .api }
9
function element(name: string): (html: any) => any;
10
```
11
12
### Parameters
13
14
- `name`: HTML tag name to use for the underline element (e.g., "u", "span", "em")
15
16
### Returns
17
18
A function that creates an HTML element with the specified tag name for underline styling.
19
20
### Usage Example
21
22
```javascript
23
const mammoth = require("mammoth");
24
25
// Create underline element using <u> tag
26
const underlineElement = mammoth.underline.element("u");
27
28
// Create underline element using <span> with class
29
const underlineSpan = mammoth.underline.element("span");
30
```
31
32
## Underline Style Mapping
33
34
By default, underlining in Word documents is ignored since it can be confused with links in HTML. However, you can enable underline processing using style mappings.
35
36
### Basic Underline Mapping
37
38
```javascript
39
const options = {
40
styleMap: [
41
"u => em" // Convert underlines to emphasis
42
]
43
};
44
45
mammoth.convertToHtml({path: "document.docx"}, options);
46
```
47
48
### Advanced Underline Mappings
49
50
```javascript
51
const options = {
52
styleMap: [
53
"u => u", // Convert to HTML <u> tag
54
"u => span.underline", // Convert to span with CSS class
55
"u => strong", // Treat underlines as bold
56
"u:lang(en) => em" // Language-specific underline handling
57
]
58
};
59
```
60
61
## Style Mapping Examples
62
63
### Converting Underlines to Different Elements
64
65
```javascript
66
// Convert underlines to emphasis
67
const emphasisOptions = {
68
styleMap: ["u => em"]
69
};
70
71
// Convert underlines to spans with CSS class
72
const spanOptions = {
73
styleMap: ["u => span.underlined-text"]
74
};
75
76
// Convert underlines to strong tags
77
const strongOptions = {
78
styleMap: ["u => strong"]
79
};
80
81
// Ignore underlines completely (default behavior)
82
const ignoreOptions = {
83
styleMap: [] // No mapping for 'u' means underlines are ignored
84
};
85
```
86
87
### Combining with Other Style Mappings
88
89
```javascript
90
const options = {
91
styleMap: [
92
// Text formatting
93
"b => strong",
94
"i => em",
95
"u => span.underline",
96
"strike => del",
97
98
// Paragraph styles
99
"p[style-name='Heading 1'] => h1",
100
"p[style-name='Heading 2'] => h2",
101
"p[style-name='Code Block'] => pre",
102
103
// Character styles
104
"r[style-name='Code'] => code",
105
"r[style-name='Emphasis'] => em"
106
]
107
};
108
109
mammoth.convertToHtml({path: "document.docx"}, options);
110
```
111
112
## Default Style Behaviors
113
114
Mammoth has default behaviors for common text formatting:
115
116
- **Bold**: Converted to `<strong>` tags
117
- **Italic**: Converted to `<em>` tags
118
- **Underline**: Ignored by default (no HTML output)
119
- **Strikethrough**: Converted to `<s>` tags
120
- **Superscript**: Converted to `<sup>` tags
121
- **Subscript**: Converted to `<sub>` tags
122
123
### Overriding Default Behaviors
124
125
```javascript
126
const options = {
127
styleMap: [
128
"b => span.bold", // Override bold to use span instead of strong
129
"i => span.italic", // Override italic to use span instead of em
130
"u => u", // Enable underline (normally ignored)
131
"strike => span.strike" // Override strikethrough to use span instead of s
132
]
133
};
134
```
135
136
## CSS Integration
137
138
When using CSS classes in style mappings, you'll need to provide corresponding CSS:
139
140
```css
141
/* CSS for custom underline styles */
142
.underline {
143
text-decoration: underline;
144
}
145
146
.underlined-text {
147
text-decoration: underline;
148
color: blue;
149
}
150
151
.custom-emphasis {
152
text-decoration: underline;
153
font-style: italic;
154
color: #cc0000;
155
}
156
```
157
158
```javascript
159
// Use the CSS classes in style mappings
160
const options = {
161
styleMap: [
162
"u => span.underline",
163
"u[custom-style='important'] => span.custom-emphasis"
164
]
165
};
166
```
167
168
## Style Mapping Syntax Reference
169
170
The underline element can be targeted using various selectors:
171
172
```javascript
173
const styleMapExamples = [
174
"u => em", // All underlines to emphasis
175
"u[style-name='Important'] => strong", // Underlines with specific style
176
"u:lang(en) => em", // Language-specific underlines
177
"u.custom-class => span.highlight" // Underlines with CSS class
178
];
179
```
180
181
## Practical Examples
182
183
### Document with Emphasis Underlines
184
185
```javascript
186
// For documents where underlines indicate emphasis
187
const emphasisDocument = {
188
styleMap: [
189
"u => em", // Underlines become emphasis
190
"b => strong", // Bold remains strong
191
"i => span.italic" // Italic becomes span for styling control
192
]
193
};
194
195
mammoth.convertToHtml({path: "emphasis-doc.docx"}, emphasisDocument);
196
```
197
198
### Legal Document with Preserved Underlines
199
200
```javascript
201
// For legal documents where underlines should be preserved
202
const legalDocument = {
203
styleMap: [
204
"u => u", // Preserve underlines as <u>
205
"p[style-name='Signature'] => p.signature" // Special signature styles
206
]
207
};
208
209
mammoth.convertToHtml({path: "legal-doc.docx"}, legalDocument);
210
```
211
212
### Academic Paper with Custom Styling
213
214
```javascript
215
// For academic papers with specific formatting needs
216
const academicPaper = {
217
styleMap: [
218
"u => span.term", // Underlined terms
219
"b => strong", // Bold for emphasis
220
"i => em", // Italic for emphasis
221
"p[style-name='Definition'] => div.definition" // Definition blocks
222
]
223
};
224
225
mammoth.convertToHtml({path: "paper.docx"}, academicPaper);
226
```