What is the best way to convert a docx with custom styles to epub?

[Gogmoth]

Hello everyone, I've written a book in Word 2019 using a template I created myself with some custom styles based on existing ones. For example, I used the modified Heading 2 style and called it Internal Heading, and so on with all the logical styles, hoping to later obtain the h1, h2, h3, separator, etc., in the conversion. In the case of Internal Heading, it should become h2, for example. I've tried Pandoc using Lua styles and adding CSS and fonts in Woff, but I can't get it to differentiate the styles. It uses <p> for everything, without any page breaks, everything in a row, and it can't distinguish between stories <h2>, chapters <h3>, chapter separators <separator>, or regular text <p>...
Does anyone know what I might be doing wrong triying to convert the Word 2019 DOCX with the custom styles I mentioned to an epub with the corresponding style tags? I was thinking about using Sigil to add the cover and images, but I need to fix this problem first. Can anyone help me?

[rnwst]

You can use the styles extension to ensure that your custom paragraph or character styles are captured as attributes on Divs or Spans. You can subsequently use a Lua filter to convert Divs and Spans with specific attributes to their most appropriate AST representations.

I'm not sure what you mean by

I've tried Pandoc using Lua styles and adding CSS and fonts in Woff, but I can't get it to differentiate the styles.

[Gogmoth]

Thank you for your reply. Let me clarify what I’m doing, as it might help better explain where the issue lies.

I'm trying to convert a .docx document (written in Word 2019) to EPUB using Pandoc, while preserving a set of custom paragraph styles I've created in Word, such as:

• "Titulo Lovecraft" → should become <h1>
• "Titulo Interno Lovecraft" → should become <h2>
• "Capitulo Lovecraft" → should become <h3>
• "Separador Lovecraft" → should be rendered as a visual break or horizontal rule
• "Fell" → should be styled as a decorative paragraph
• "Normal Lovecraft" → should be the main paragraph text (i.e., <p>)

The styles are applied correctly in Word, and I verified that they are preserved in the DOCX structure (including when I unzip the .docx and inspect styles.xml and document.xml).

My current workflow:

1. I run Pandoc with this command:

pandoc "document.docx" -o output.epub --extract-media=media --lua-filter=styles.lua

2. I’m using a custom Lua filter (styles.lua) intended to map the custom Word styles to semantic HTML tags (<h2>, <h3>, <p>, etc.).

3. I’ve also created and included a style_map.txt (though I understand that might only apply to Calibre or other tools, not Pandoc).

4. The EPUB output, however, flattens everything into <p> tags, ignoring my styles. For instance:

   • All paragraphs become <p>
   • Headings are lost unless I use the default Word styles (Heading 1, Heading 2, etc.)
   • No <h2>, <h3>, or separators are generated

I read that the styles extension might help capture these custom Word styles as Div or Span attributes, but I’m unsure if it's fully supported when converting .docx to EPUB or how to enable it correctly for this purpose.

Do I need to first convert the .docx to .html or .json with +styles, and then use a Lua filter to map the styles? Or is there a better way to intercept these Word paragraph styles directly during .docx → epub3 conversion?

Note: I’m attaching the ZIP with my Lua filter, stylesheet, and Word style template (.dotx) so you can inspect how the styles are defined. I’m not sharing the actual .docx as it contains unpublished copyrighted content, but the .dotx reflects all custom styles exactly as used in the book.

Any advice would be appreciated!

pandoc test.zip

[rnwst]

When any document is converted, it is first transformed into pandoc's internal document representation, the AST. Afterwards, the AST is written to the output format. You can examine your document's AST by converting to the native format:

pandoc document.docx -t native

Now try again, but with the styles extension:

pandoc -f docx+styles document.docx -t native

Your paragraphs should now be wrapped in Divs and Spans with the custom-styles attribute. You can subsequently use a Lua filter to replace Divs of a specific style with Headers, for example. Let me know if you need help with this.

Once you are happy with the AST you are getting, you can create your EPUB:

pandoc -f docx+styles document.docx -L filter.lua -o output.epub

[Gogmoth]

Thank you so much for your help! Your suggestion to inspect the AST with -t native was exactly what I needed — it allowed me to realize that Pandoc converts my custom Word styles into hyphenated class names (e.g., titulo-lovecraft instead of TituloLovecraft). Once I updated my Lua filter to use those hyphenated names, the transformation worked as expected and my headers are now correctly mapped to <h1>, <h2>, and <h3>.

I also followed your command structure and slightly extended it for my use case:

pandoc -f docx+styles entrada.docx -L filter.lua -c fuentes.css --metadata title="Las puertas del abismo" --split-level=2 -o salida.epub

• -L filter.lua applies the Lua filter that maps styles to headers and inserts visual separators.
• -c fuentes.css loads a stylesheet that handles fonts and visual layout.
• --metadata title=... sets the correct EPUB title (it was showing as Untitled before).
• --split-level=2 splits the EPUB into separate HTML files per <h1> and <h2>, which is perfect for my structure (book title, story titles, chapter titles).

So far, everything works as intended except one last issue:

🔸 I'm trying to insert <hr class="salto-h2"> (or similar) between certain elements to simulate page breaks using CSS. These <hr> elements are generated in the Lua filter like this:

pandoc.RawBlock("html", '<hr class="salto-h2" />')

...and styled in fuentes.css with:

hr.salto-h2 {
  page-break-before: always;
  border: none;
  height: 2em;
}

However, after inspecting the EPUB's output files (.xhtml), I confirmed that these <hr> elements are not present. The Lua filter seems to execute without error, but those blocks are simply missing from the output. This is preventing the simulated page breaks from working, even though the CSS is properly written.

📎 I've attached my current filter.lua and fuentes.css files for reference in case you spot something wrong with the implementation.
lua+css.zip

Any ideas on why the raw <hr> blocks might not be making it into the final EPUB? I'm close to the final result — thanks again for getting me this far!

[rnwst]

Have you confirmed that your Lua filter is adding these RawBlock elements to the AST (using -t native)?

[Gogmoth]

Hi, thanks for your comment!

✅ I’ve now solved the page break issue by using the option --split-level=4. This makes Pandoc split the EPUB output into separate XHTML files at every heading level up to <h4>, so each internal title (h2), chapter title (h3), etc., now starts on a new “page” as expected by EPUB readers.

📘 The updated command I'm using is:

pandoc -f docx+styles entrada.docx -L filter.lua -c fuentes.css --metadata title="Las puertas del abismo" --split-level=4 --toc --toc-depth=4 -o salida.epub

🔍 However, my current issue is:

The custom styles defined in the DOCX file — such as Normal Lovecraft, Fell, and Separador Lovecraft — are correctly preserved in the Pandoc AST output when using:

pandoc -f docx+styles entrada.docx -t native -o ast_salida.txt

This is confirmed by the presence of structures like:

Div ("", [], [("custom-style", "Normal Lovecraft")]) [...]
Span ("", [], [("custom-style", "Fell")]) [...]
Div ("", [], [("custom-style", "Separador Lovecraft")]) [...]

However, when converting the same .docx to .epub3 using:

pandoc -f docx+styles entrada.docx -L filter.lua -c fuentes.css --metadata title="Las puertas del abismo" --split-level=4 --toc --toc-depth=4 -o salida.epub

...these custom styles are NOT mapped into HTML classes in the resulting EPUB, unless they are handled explicitly via Lua filters.

✅ Current Situation

The Lua filter does receive the correct custom-style attributes in the AST, so detection is not the problem.
What doesn't happen automatically is the transformation into meaningful HTML tags or classes.

✅ What I Need

I want to ensure the final EPUB has elements like:

<p class="normal-lovecraft">...</p>
<span class="fell">...</span>
<p class="separador-lovecraft">◆◆◆</p>

🔍 In particular, the Fell style is used intentionally in two different contexts in the DOCX:

• When applied to an entire paragraph, it should be rendered as:
  <p class="fell">Entire sentence in Fell style.</p>

• When applied to a fragment inside a paragraph, it should become:
  <p>Text before <span class="fell">this part</span> continues here.</p>

This dual usage is by design, and I’m using it deliberately to convey typographic nuance in the final EPUB.

Is there a recommended way to support this dual output cleanly — or should this always be handled manually via a Lua filter?

I’m already using Lua if necessary, but I'd like to confirm that this kind of style-dependent transformation is not achievable with CSS alone in the Pandoc DOCX → EPUB3 pipeline.

Examples:
ast_salida.txt
entrada.docx

[rnwst]

Your custom styles are not mapped into HTML classes because they are not classes. They are attributes. They are, however, mapped into HTML attributes. You should see data-custom-style="..." in your output. If you want to transform attributes into classes, you need to use a filter for that.

[Gogmoth]

Thanks again for the clarification.

You're right — the styles are preserved as data-custom-style attributes in the HTML output (e.g., <div data-custom-style="Normal Lovecraft">). That’s working correctly.

To transform them into usable HTML classes, I’ve written the following Lua filter:

function Div(el)
  local estilo = el.attr and el.attr.attributes and el.attr.attributes["data-custom-style"]

  if estilo == "Normal Lovecraft" then
    local nuevo = {}
    for _, elem in ipairs(el.content) do
      if elem.t == "Para" then
        table.insert(nuevo, pandoc.Para(elem.content, pandoc.Attr("", {"normal-lovecraft"})))
      else
        table.insert(nuevo, elem)
      end
    end
    return nuevo

  elseif estilo == "Fell" then
    local nuevo = {}
    for _, elem in ipairs(el.content) do
      if elem.t == "Para" then
        table.insert(nuevo, pandoc.Para(elem.content, pandoc.Attr("", {"fell"})))
      else
        table.insert(nuevo, elem)
      end
    end
    return nuevo

  elseif estilo == "Separador Lovecraft" then
    return pandoc.Para(el.content, pandoc.Attr("", {"separador-lovecraft"}))
  end

  return el
end

✅ The issue: Although the filter parses without error, it doesn't produce the expected HTML output. Instead of converting these blocks into <p class="normal-lovecraft">...</p> or similar, the resulting EPUB still contains raw data-custom-style attributes.

🔍 Here’s an example of the actual HTML from the generated .epub:

<div data-custom-style="Normal Lovecraft">
  <p>Normal Lovecraft Normal Lovecraft Normal Lovecraft Normal Lovecraft</p>
</div>

<div data-custom-style="Normal Lovecraft">
  <p>Normal Lovecraft <span data-custom-style="Fell Car">Fell Fell Fell Fell</span> Normal Lovecraft</p>
</div>

<div data-custom-style="Separador Lovecraft">
  <p>◆◆◆</p>
</div>

As you can see, the filter didn’t rewrite them to:

<p class="normal-lovecraft">...</p>
<span class="fell">Fell Fell Fell</span>
<p class="separador-lovecraft">◆◆◆</p>

✅ Files attached: I'm including both the .lua filter and the generated .epub file, in case you’d like to inspect the results and help identify what might be going wrong in the filter logic.

Thanks in advance for any tips or corrections — much appreciated!

lua+epub.zip

[rnwst]

Your filter doesn't work because Para elements in pandoc's AST can't have attributes (see also #10768). Instead, you could modify the classes on the Div directly, rather than replacing the Div with a Para. Alternatively, you could return a RawBlock with contents <p class="...">Para content...</p>, if you don't want the Div wrapper.

Btw, I recommend you give pandoc-lua-types a try (shameless plug). When I opened up your filter in my text editor, it picked up on the mistakes straight away:

[Gogmoth]

Hi @rnwst and everyone, I wanted to provide a detailed update on my testing following your guidance, and explain why the issue with Word paragraph styles persists in the EPUB output despite our best efforts.

---

🧪 What I tried

1. Input DOCX: with custom Word paragraph styles like Normal Lovecraft, Fell, etc.

2. Lua filter to intercept Div blocks and convert data-custom-style="..." into proper class="...", for example:

   function Div(el)
     local estilo = el.attr.attributes and el.attr.attributes["data-custom-style"]
     if estilo then
       local clase = estilo:lower():gsub(" ", "-") -- e.g. "Fell" → "fell"
       return pandoc.Div(el.content, pandoc.Attr("", { clase }))
     end
     return el
   end

3. Validated the filter syntax using the Pandoc plugin for Lua in VS Code.

4. Ran Pandoc with -f docx+styles, confirmed via ast_filtrado.txt output that the AST was indeed modified as expected: Div replaced, data-custom-style removed, class applied.

---

🔍 What actually happens

• The AST confirms the filter did its job.

• But the final .epub (inspected in Sigil or by unzipping) still contains:

  <div data-custom-style="Fell">
    <p>Some text</p>
  </div>

  instead of the expected:

  <div class="fell">
    <p>Some text</p>
  </div>

• Likewise, injecting RawBlock("<p class=…>") is ignored — EPUB writer discards it, per issue Add Attribute Support for Paragraphs: Enabling Para Elements to Carry HTML Classes, IDs, and Custom Attributes #10768.

---

🚧 Why this matters

• Stylesheet defines .fell and .normal-lovecraft correctly, but they don’t apply because the HTML doesn’t use those classes.
• Pandoc’s EPUB writer reconstructs the structure in a canonical way and appears to ignore or restore the original data-custom-style unless it matches Pandoc’s own internal expectations.

---

✔️ Conclusion

Following your advice, I modified the Div via pandoc.Div(el.content, pandoc.Attr("", { class })), which is theoretically what you recommended. Yet, despite the AST reflecting that change, the EPUB writer seems to drop or override it during serialization.

---

❓ Questions for the developers:

• Is there an extra normalization step in the EPUB writer that disregards Pandoc.Attr on Div, perhaps restoring data-custom-style or ignoring unknown attributes?
• Is there any way to reliably bridge Word style names → EPUB classes, using Lua filters or metadata, such that the final .xhtml reflects the intended class="fell" etc.?

---

Thanks again for your guidance—I’ve been down this rabbit hole for days and would appreciate any insights into ways to make the custom paragraph classes survive into the final EPUB. 🙏

[denismaier]

Can you share a mimimal native ast (showing the correct structure)?

[rnwst]

In your filter, you are checking for the data-custom-style attribute. You should be checking for custom-style instead. The data- prefix only gets added when the document is converted to EPUB/HTML. I don't believe you have actually confirmed that the AST is modified by your filter.

[Gogmoth]

Hi again @rnwst and @denismaier,

Thanks so much for your help and clarifications. I’ve now reviewed everything step by step, and I'm attaching a .zip in this post with all the relevant files, including:

• entrada.docx (input file with custom Word paragraph styles)
• filter.lua (the Lua filter)
• fuentes.css (CSS stylesheet)
• ast_filtrado.txt (the filtered AST in native format)
• salida.epub (the output EPUB file)

---

✅ Lua filter behavior

I followed your advice and updated the Lua filter to correctly intercept the custom-style attribute (not data-custom-style). Here's the relevant part:

function Div(el)
  local estilo = el.attr.attributes and el.attr.attributes["custom-style"]
  if estilo then
    local clase = estilo:lower():gsub(" ", "-")
    return pandoc.Div(el.content, pandoc.Attr("", { clase }))
  end
  return el
end

This filter is applied using the command:

pandoc -f docx+styles entrada.docx --lua-filter=filter.lua \
  -c fuentes.css \
  --epub-embed-font=fonts/IMFellDWPicaSC-Regular.ttf \
  --epub-embed-font=fonts/Merriweather-Regular.ttf \
  --epub-embed-font=fonts/Merriweather-Italic-VariableFont_opsz,wdth,wght.ttf \
  --metadata title="Las puertas del abismo" \
  --toc --toc-depth=4 --split-level=4 \
  -o salida.epub

---

🧪 AST verification

I exported the AST with:

pandoc -f docx+styles entrada.docx --lua-filter=filter.lua -t native -o ast_filtrado.txt

In the filtered AST, we clearly see:

Div ("",["fell"],[Para [...]])

✅ This confirms that:

• The custom-style attribute was detected.
• The class fell was added as expected.
• The Div structure was preserved and modified correctly.

---

❌ EPUB output: unexpected result

However, when inspecting salida.epub in Sigil or unzipping it manually, the XHTML files still show:

<div data-custom-style="Fell">
  <p>...</p>
</div>

The class is not applied, and the EPUB writer seems to preserve the original data-custom-style instead of using the modified class from the AST.

This seems to confirm what was mentioned in issue #10768: the EPUB writer may restore the original Word structure based on the embedded style map or some fallback behavior, ignoring changes made to Div attributes by the Lua filter.

---

❓ Question

Given that the AST is correct, but the EPUB output overrides the modified attributes, is there any known way to make these class changes survive through to the XHTML output?

Should I consider switching to a different approach (e.g., pre-processing DOCX into markdown first, or using RawBlock HTML instead of Divs)? I would prefer to retain clean semantic HTML if possible.

Thanks again — your help has been invaluable, and I’ve attached the full .zip with everything so you can reproduce the issue.

lua_trouble.zip

[rnwst]

The filter you have listed above works fine for me and replaces the custom attributes with classes when running pandoc -f docx+styles .\entrada.docx -L .\filter2.lua -o salida.epub using the DOCX you have attached and the filter you have listed above:

function Div(el)
  local estilo = el.attr.attributes and el.attr.attributes["custom-style"]
  if estilo then
    local clase = estilo:lower():gsub(" ", "-")
    return pandoc.Div(el.content, pandoc.Attr("", { clase }))
  end
  return el
end

In the zip archive you have attached, the filter doesn't work because it uses data-custom-style instead of custom-style, as I have pointed out in my comment above.

I don't think I can do anything else to help you at this point, so please don't ping me anymore here. Thanks.

[Gogmoth]

Thank you very much, especially @rnwst, for the detailed explanation and for testing it on your side.

You were absolutely right — my filter was still using "data-custom-style" instead of "custom-style" at the AST level. That was the root of the issue.

I've now corrected the filter accordingly (I’ll attach the updated .lua in case others find it helpful), and everything works as expected, including inline Span elements with partial styles like <span class="fell-car"> and <span class="normal-lovecraft-car">.

I verified the result both in the final EPUB and by generating the AST (-t native) after the filter is applied, to confirm that every style is properly interpreted and converted.

I recognize this was entirely my misunderstanding — partly due to the language barrier, as English isn’t my first language, and I may have misread your instructions initially.

Thanks again for your time and generosity. I won’t ping anyone further on this thread, but I hope the final version of the filter helps others with similar needs.

Best regards,
filter.zip