Search code examples
docxpandoc

How do I add custom formatting to docx files generated in Pandoc?

How can I add custom formatting to docx files generated by Pandoc from, say, Markdown? For example, can I highlight text or center it? Can I restyle links, etc?

I know that I can change styles for default elements, like headings, by using a --reference-doc (generated with pandoc -o custom-reference.docx --print-default-data-file reference.docx), but I'd like to introduce additional styles.

Solution

  • There are basically 3 ways to customize docx output in Pandoc:

    1. [Mentioned in the question] Customize default elements (like headings and blockquotes) by editing the reference doc.
    2. Customize other elements (like hyperlinks, or default paragraph font), by editing those styles in the reference doc.
    3. Add custom 'elements' (styles) by adding them to the reference doc.

    Option 1. Customize default elements

    1. Generate a reference doc (as mentioned in the question: pandoc -o custom-reference.docx --print-default-data-file reference.docx). It will have a bunch of content, representing common Pandoc components like headings and blockquotes (see picture at the end).

    2. In the Styles menu at the top of Word, find the style you want to change and edit it to be what you'd like (I'm not sure if you can simply edit the text's style directly).

    Option 2: Customize other elements

    There are more styles than the ones that appear in the reference document text and in the "Style gallery." For example, you can customize hyperlinks (e.g. color).

    1. Generate a reference doc (or use the one you have from above).

    2. Click the expand button in the Styles section to show the Styles pane (see below).

      Styles overflow menu

    3. Find the style you want, then edit it.

    Also:

    • You can click an option in the dropdown beside each style to add it to the Style gallery, for easier editing.
    • You can add text with that style to the document itself, if you'd like to preview what it will look like in context.

    Option 3: Add custom styles

    This is probably the most relevant to the question. If you want to introduce custom elements beyond the default ones Pandoc provides and Word provides, you can simply add custom styles to the reference document. For example, you can create a style for highlighted text or centered text, or a style for large code blocks.

    1. Generate a reference doc (or use the one you have from above).

    2. Add some text to the document using the base style you want---the style you want to base your new custom style on. For example, if you want "normal text but highlighted," write some new text that uses the "Normal" or "Body text" style.

    3. Click the dropdown in the Styles gallery.

    4. Click Create a Style

    5. Name the style, whatever you'd like.

    6. Click Modify... and customize the style however you'd like. You can always get to this menu later by right-clicking the style in the gallery and clicking "Modify..."

    7. Save the document.

    8. In the text you will convert to docx, add divs and spans with the appropriate custom-style attribute whenever you want to consume it. For example, if you have a paragraph style called Super big and a character style called Highlighted text:

      <div custom-style="Super big">My super big text</div>

Normal text. <span custom-style="Highlighted text">This is highlighted</span>.

      Pandoc will apply those custom styles for you!

    References

    The default reference doc: The default reference doc