@@ -3827,6 +3827,54 @@ To disable highlighting, use the `--no-highlight` option.
38273827
38283828[highlighting-kate]: https://github.com/jgm/highlighting-kate
38293829
3830+Custom Styles in Docx Output
3831+============================
3832+
3833+By default, pandoc's docx output applies a predefined set of styles for
3834+blocks such as paragraphs and block quotes, and uses largely default
3835+formatting (italics, bold) for inlines. This will work for most
3836+purposes, especially alongside a `reference.docx` file. However, if you
3837+need to apply your own styles to blocks, or match a preexisting set of
3838+styles, pandoc allows you to define custom styles for blocks and text
3839+using `div`s and `span`s, respecitively.
3840+
3841+If you define a `div` or `span` with the attribute `custom-style`,
3842+pandoc will apply your specified style to the contained elements. So,
3843+for example,
3844+
3845+ <span custom-style="Emphatically">Get out,</span> he said.
3846+
3847+would produce a docx file with "Get out," styled with character
3848+style `Emphatically`. Similarly,
3849+
3850+ Dickinson starts the poem simply:
3851+
3852+ <div custom-style="Poetry">
3853+ | A Bird came down the Walk---
3854+ | He did not know I saw---
3855+ </div>
3856+
3857+Would style the two contained lines with the `Poetry` paragraph style.
3858+
3859+If the styles are not yet in your reference.docx, they will be defined
3860+in the output file as inheriting from normal text. If they are already
3861+defined, pandoc will not alter the definition.
3862+
3863+This feature allows for greatest customization in conjunction with
3864+[pandoc filters]. If you want all paragraphs after block quotes to be
3865+indented, you can write a filter to apply the styles necessary. If you
3866+want all italics to be transformed to the `Emphasis` character style
3867+(perhaps to change their color), you can write a filter which will
3868+transform all italicized inlines
3869+
3870+ Emph <inlines>
3871+
3872+to
3873+
3874+ Span ("", [], [("custom-style", "Emphasis")] <inlines>
3875+
3876+[pandoc filters]: http://pandoc.org/scripting.html
3877+
38303878Custom writers
38313879==============
38323880