Tech Talk: Converting Dynamic HTML Content to Editable DOCX Using Pandoc #10754

vishalmudgal4996 · 2025-04-04T11:27:36Z

vishalmudgal4996
Apr 4, 2025

Tech Talk: Converting Dynamic HTML Content to Editable DOCX Using Pandoc

📌 Introduction to Pandoc

Pandoc is a powerful, open-source universal document converter. It enables seamless conversions between numerous formats, including Markdown, HTML, PDF, DOCX, and many more. It is praised for its flexibility, customizability, and strong community support.

Official Documentation: [Pandoc Documentation](https://pandoc.org/MANUAL.html)

🚩 Our Use Case

In our Question Bank Generation (QBG) project, we generate highly dynamic question content, featuring images, QR codes, mathematical equations, and multilingual support.

Initially, this content was delivered as PDFs via native browser print engines (HTML-to-PDF)
NEET-JEE_DPP 12 (1).pdf
. However, a critical requirement emerged: providing editable DOCX files for the Operations team to directly handle minor corrections and enabling the Test team to adapt content flexibly for diverse test formats.

🔍 Evaluating Commercial Solutions (Apryse)

Initially, we explored commercial solutions like Apryse (
output_paragraphs_and_tables.docx
), but the results were unsatisfactory for our dynamic and complex formatting requirements.

🌟 Why Choose Pandoc?

After thorough consideration, Pandoc stood out due to:

✅ Open-source availability
✅ Effective handling of complex dynamic content
✅ Extensive custom styling options via Lua scripting
✅ Strong community support

🚀 Getting Started with Pandoc

1. Installation

Pandoc installation via Homebrew (macOS):

brew install pandoc

2. Basic Conversion (HTML → DOCX)

Simple command example:

pandoc input.html -o output.docx

Dynamic Path Generation in Our Implementation:

const uniqueDocxPath = `temp/${IdGenerator.generateUniqueId()}.docx`;
const uniqueHtmlPath = `temp/${IdGenerator.generateUniqueId()}.html`;

const command = `pandoc '${uniqueHtmlPath}' -o '${uniqueDocxPath}'`;

This basic conversion only outputs text content without styling.

🛠️ Demo: Pandoc HTML-to-DOCX Conversion

Example: Simple Text and Styling

HTML Input (input.html):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Pandoc Test - Simple Formatting</title>
</head>
<body>
  <h1>Welcome to Pandoc!</h1>
  <p>
    This is a simple paragraph demonstrating
    <strong>bold text</strong>, 
    <em>italic text</em>, and 
    <u>underlined text</u>.
  </p>
  <ul>
    <li>First item</li>
    <li>Second item</li>
    <li>Third item</li>
  </ul>
</body>
</html>

Pandoc Command:

pandoc input.html -o output.docx

output.docx

Live Demo: [Try Pandoc Online](https://pandoc.org/try/)

🎨 Styling DOCX Output

HTML uses CSS (Cascading Style Sheets) to define and control visual styles directly within documents. However, when converting HTML content into DOCX format, Pandoc does not directly interpret inline CSS or HTML-specific styling. This limitation arises because:

DOCX documents (used by Microsoft Word) are structured using the Office Open XML (OOXML) format, a language distinct from HTML/CSS.
Pandoc acts as a converter rather than a browser renderer, meaning it doesn't process visual styles embedded within HTML or CSS directly.

Therefore, Pandoc requires an intermediary, explicitly defined styling reference to apply desired visual formatting to DOCX files. This intermediary is called a reference DOCX file.

Generating and Customizing Reference DOCX

Extract Pandoc’s default reference DOCX:

pandoc -o custom-reference.docx --print-default-data-file reference.docx

Customize the styles by editing custom-reference.docx directly in Microsoft Word, then save your changes.

custom-reference.docx

Applying Customized Styles

Use your customized DOCX as a reference:

const uniqueDocxPath = `temp/${IdGenerator.generateUniqueId()}.docx`;
const uniqueHtmlPath = `temp/${IdGenerator.generateUniqueId()}.html`;
const styleReferenceFilePath = 'assets/custom-reference.docx';

const command = `pandoc --standalone --reference-doc='${styleReferenceFilePath}' --wrap=preserve '${uniqueHtmlPath}' -o '${uniqueDocxPath}'`;

Your DOCX will now reflect the defined styles.

QBG Style Reference file and result:

html-to-docx-style-reference.docx
zzxlqpcmoe1fd8rp9os74nokl (1).docx

🔧 Advanced Custom Styling

Pandoc can map custom HTML attributes directly to DOCX styles.

Step-by-Step Guide:

Define custom styles in your reference DOCX.
Apply custom attributes in HTML:

<div custom-style="indentation">
  <span custom-style="bold_char">{{ que?.questionCount }}.</span>
  <span custom-style="tab"></span>
  <span>
    <mathjax [content]="que?.content?.[languageName] || ''"></mathjax>
  </span>
</div>

Pandoc automatically recognizes these custom-style attributes.

📝 Manipulating Output with Lua Filters

Advanced manipulations (like explicit tabs) can be done using Lua filters.

Lua Filter Example (filter.lua):

function Span(elem)
  if elem.attributes["custom-style"] == "tab" then
    return pandoc.RawInline('openxml', '<w:r><w:tab/></w:r>')
  elseif elem.attributes["custom-style"] == "tab_0_75" then
    return pandoc.RawInline('openxml', '<w:r><w:tab/></w:r>')
  end
end

Command with Lua filter:

pandoc input.html --lua-filter='filter.lua' --reference-doc='custom-reference.docx' -o output.docx

📚 Understanding Pandoc Commands & Flags

Complete Example Command:

pandoc --standalone --reference-doc='custom-reference.docx' --wrap=preserve input.html -o output.docx

pandoc: Initiates conversion.
input.html: Input file.
-o output.docx: Output file and format.
--standalone: Generates a self-contained document.
--reference-doc: Applies customized DOCX styles.
--wrap=preserve: Maintains original formatting without unwanted line breaks.

Lua Filter Flag:

--lua-filter='filter.lua': Applies custom Lua script during conversion.

📊 Workflow Integration in QBG

Complete Conversion Flow:

QBG generates questions.
Questions → DOCX-template service.
HTML templates prepared.
HTML sent to html-to-docx API endpoint.
Pandoc converts HTML to DOCX applying styles/Lua filters.
DOCX file URL returned; downloaded by the service.

Diagrammatic Representation:

✅ Key Advantages of Pandoc

Open Source: Cost-free, highly customizable.
Extensible Solution: Supports advanced styling (reference DOCX + Lua scripts).
Robust Community: Active GitHub community for support.
Complex Data Support: Handles equations, multilingual content, images, QR codes.
Editable Format: Empowers Operations/Test teams with direct editing capabilities.

📎 Attachments and References

Official Pandoc Documentation: [Pandoc Manual](https://pandoc.org/MANUAL.html)
GitHub Issue Reference: [Pandoc GitHub Issue #9927](Aligning mtable with Regular Text Flow in DOCX Conversion #9927)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Tech Talk: Converting Dynamic HTML Content to Editable DOCX Using Pandoc #10754

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Tech Talk: Converting Dynamic HTML Content to Editable DOCX Using Pandoc #10754

Uh oh!

vishalmudgal4996 Apr 4, 2025

Tech Talk: Converting Dynamic HTML Content to Editable DOCX Using Pandoc

📌 Introduction to Pandoc

🚩 Our Use Case

🔍 Evaluating Commercial Solutions (Apryse)

🌟 Why Choose Pandoc?

🚀 Getting Started with Pandoc

1. Installation

2. Basic Conversion (HTML → DOCX)

🛠️ Demo: Pandoc HTML-to-DOCX Conversion

Example: Simple Text and Styling

🎨 Styling DOCX Output

Generating and Customizing Reference DOCX

Applying Customized Styles

QBG Style Reference file and result:

🔧 Advanced Custom Styling

Step-by-Step Guide:

📝 Manipulating Output with Lua Filters

📚 Understanding Pandoc Commands & Flags

📊 Workflow Integration in QBG

Complete Conversion Flow:

Diagrammatic Representation:

✅ Key Advantages of Pandoc

📎 Attachments and References

🌟 Happy Converting!

Replies: 0 comments

vishalmudgal4996
Apr 4, 2025