@@ -1974,6 +1974,16 @@ input formats
19741974output formats
19751975: `markdown`, `docx`, `odt`, `opendocument`, `html`
19761976
1977+#### Extension: `styles` #### {#ext-styles}
1978+
1979+Read all docx styles as divs (for paragraph styles) and spans (for
1980+character styles) regardless of whether pandoc understands the meaning
1981+of these styles. This can be used with [docx custom
1982+styles](#custom-styles-in-docx). Disabled by default.
1983+
1984+input formats
1985+: `docx`
1986+
19771987#### Extension: `amuse` ####
19781988
19791989In the `muse` input format, this enables Text::Amuse
@@ -4490,8 +4500,60 @@ To disable highlighting, use the `--no-highlight` option.
44904500
44914501[skylighting]: https://github.com/jgm/skylighting
44924502
4493−Custom Styles in Docx Output
4494−============================
4503+Custom Styles in Docx
4504+=====================
4505+
4506+Input
4507+-----
4508+
4509+The docx reader, by default, only reads those styles that it can
4510+convert into pandoc elements, either by direct conversion or
4511+interpreting the derivation of the input document's styles.
4512+
4513+By enabling the [`styles` extension](#ext-styles) in the docx reader
4514+(`-f docx+styles`), you can produce output that maintains the styles
4515+of the input document, using the `custom-style` class. Paragraph
4516+styles are interpreted as divs, while character styles are interpreted
4517+as spans.
4518+
4519+For example, using the `custom-style-reference.docx` file in the test
4520+directory, we have the following different outputs:
4521+
4522+Without the `+styles` extension:
4523+
4524+ $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
4525+ This is some text.
4526+
4527+ This is text with an *emphasized* text style. And this is text with a
4528+ **strengthened** text style.
4529+
4530+ > Here is a styled paragraph that inherits from Block Text.
4531+
4532+And with the extension:
4533+
4534+ $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
4535+ ::: {custom-style="FirstParagraph"}
4536+ This is some text.
4537+ :::
4538+
4539+ ::: {custom-style="BodyText"}
4540+ This is text with an
4541+ *[[emphasized]{custom-style="Emphatic"}]{custom-style="Emphatic"}* text
4542+ style. And this is text with a
4543+ **[[strengthened]{custom-style="Strengthened"}]{custom-style="Strengthened"}**
4544+ text style.
4545+ :::
4546+
4547+ ::: {custom-style="MyBlockStyle"}
4548+ > Here is a styled paragraph that inherits from Block Text.
4549+ :::
4550+
4551+With these custom styles, you can use your input document as a
4552+reference-doc while creating docx output (see below), and maintain the
4553+same styles in your input and output files.
4554+
4555+Output
4556+------
44954557
44964558By default, pandoc's docx output applies a predefined set of styles for
44974559blocks such as paragraphs and block quotes, and uses largely default