tessl/npm-mammoth

Convert Word documents from docx to simple HTML and Markdown

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Style Utilities

Name: tessl/npm-mammoth
Author: tessl

Utilities for handling underline and other styling elements in document conversion.

underline.element

Create underline element with specified HTML tag name.

function element(name: string): (html: any) => any;

Parameters

name: HTML tag name to use for the underline element (e.g., "u", "span", "em")

Returns

A function that creates an HTML element with the specified tag name for underline styling.

Usage Example

const mammoth = require("mammoth");

// Create underline element using <u> tag
const underlineElement = mammoth.underline.element("u");

// Create underline element using <span> with class
const underlineSpan = mammoth.underline.element("span");

Underline Style Mapping

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.

Basic Underline Mapping

const options = {
    styleMap: [
        "u => em"  // Convert underlines to emphasis
    ]
};

mammoth.convertToHtml({path: "document.docx"}, options);

Advanced Underline Mappings

const options = {
    styleMap: [
        "u => u",                    // Convert to HTML <u> tag
        "u => span.underline",       // Convert to span with CSS class
        "u => strong",               // Treat underlines as bold
        "u:lang(en) => em"          // Language-specific underline handling
    ]
};

Style Mapping Examples

Converting Underlines to Different Elements

// Convert underlines to emphasis
const emphasisOptions = {
    styleMap: ["u => em"]
};

// Convert underlines to spans with CSS class
const spanOptions = {
    styleMap: ["u => span.underlined-text"]
};

// Convert underlines to strong tags
const strongOptions = {
    styleMap: ["u => strong"]
};

// Ignore underlines completely (default behavior)
const ignoreOptions = {
    styleMap: []  // No mapping for 'u' means underlines are ignored
};

Combining with Other Style Mappings

const options = {
    styleMap: [
        // Text formatting
        "b => strong",
        "i => em", 
        "u => span.underline",
        "strike => del",
        
        // Paragraph styles
        "p[style-name='Heading 1'] => h1",
        "p[style-name='Heading 2'] => h2",
        "p[style-name='Code Block'] => pre",
        
        // Character styles
        "r[style-name='Code'] => code",
        "r[style-name='Emphasis'] => em"
    ]
};

mammoth.convertToHtml({path: "document.docx"}, options);

Default Style Behaviors

Mammoth has default behaviors for common text formatting:

Bold: Converted to <strong> tags
Italic: Converted to <em> tags
Underline: Ignored by default (no HTML output)
Strikethrough: Converted to <s> tags
Superscript: Converted to <sup> tags
Subscript: Converted to <sub> tags

Overriding Default Behaviors

const options = {
    styleMap: [
        "b => span.bold",        // Override bold to use span instead of strong
        "i => span.italic",      // Override italic to use span instead of em
        "u => u",                // Enable underline (normally ignored)
        "strike => span.strike"  // Override strikethrough to use span instead of s
    ]
};

CSS Integration

When using CSS classes in style mappings, you'll need to provide corresponding CSS:

/* CSS for custom underline styles */
.underline {
    text-decoration: underline;
}

.underlined-text {
    text-decoration: underline;
    color: blue;
}

.custom-emphasis {
    text-decoration: underline;
    font-style: italic;
    color: #cc0000;
}

// Use the CSS classes in style mappings
const options = {
    styleMap: [
        "u => span.underline",
        "u[custom-style='important'] => span.custom-emphasis"
    ]
};

Style Mapping Syntax Reference

The underline element can be targeted using various selectors:

const styleMapExamples = [
    "u => em",                              // All underlines to emphasis
    "u[style-name='Important'] => strong",  // Underlines with specific style
    "u:lang(en) => em",                     // Language-specific underlines
    "u.custom-class => span.highlight"      // Underlines with CSS class
];

Practical Examples

Document with Emphasis Underlines

// For documents where underlines indicate emphasis
const emphasisDocument = {
    styleMap: [
        "u => em",           // Underlines become emphasis
        "b => strong",       // Bold remains strong
        "i => span.italic"   // Italic becomes span for styling control
    ]
};

mammoth.convertToHtml({path: "emphasis-doc.docx"}, emphasisDocument);

Legal Document with Preserved Underlines

// For legal documents where underlines should be preserved
const legalDocument = {
    styleMap: [
        "u => u",                           // Preserve underlines as <u>
        "p[style-name='Signature'] => p.signature"  // Special signature styles
    ]
};

mammoth.convertToHtml({path: "legal-doc.docx"}, legalDocument);

Academic Paper with Custom Styling

// For academic papers with specific formatting needs
const academicPaper = {
    styleMap: [
        "u => span.term",                   // Underlined terms
        "b => strong",                      // Bold for emphasis
        "i => em",                          // Italic for emphasis
        "p[style-name='Definition'] => div.definition"  // Definition blocks
    ]
};

mammoth.convertToHtml({path: "paper.docx"}, academicPaper);