@@ -2216,10 +2216,11 @@ output formats
22162216
22172217#### Extension: `styles` #### {#ext-styles}
22182218
2219−Read all docx styles as divs (for paragraph styles) and spans (for
2220−character styles) regardless of whether pandoc understands the meaning
2221−of these styles. This can be used with [docx custom
2222−styles](#custom-styles). Disabled by default.
2219+When converting from docx, read all docx styles as divs (for
2220+paragraph styles) and spans (for character styles) regardless
2221+of whether pandoc understands the meaning of these styles.
2222+This can be used with [docx custom styles](#custom-styles).
2223+Disabled by default.
22232224
22242225input formats
22252226: `docx`
@@ -5061,6 +5062,52 @@ Custom Styles
50615062
50625063Custom styles can be used in the docx and ICML formats.
50635064
5065+Output
5066+------
5067+
5068+By default, pandoc's docx and ICML output applies a predefined set of styles
5069+for blocks such as paragraphs and block quotes, and uses largely default
5070+formatting (italics, bold) for inlines. This will work for most
5071+purposes, especially alongside a `reference.docx` file. However, if you
5072+need to apply your own styles to blocks, or match a preexisting set of
5073+styles, pandoc allows you to define custom styles for blocks and text
5074+using `div`s and `span`s, respectively.
5075+
5076+If you define a `div` or `span` with the attribute `custom-style`,
5077+pandoc will apply your specified style to the contained elements. So,
5078+for example using the `bracketed_spans` syntax,
5079+
5080+ [Get out]{custom-style="Emphatically"}, he said.
5081+
5082+would produce a docx file with "Get out" styled with character
5083+style `Emphatically`. Similarly, using the `fenced_divs` syntax,
5084+
5085+ Dickinson starts the poem simply:
5086+
5087+ ::: {custom-style="Poetry"}
5088+ | A Bird came down the Walk---
5089+ | He did not know I saw---
5090+ :::
5091+
5092+would style the two contained lines with the `Poetry` paragraph style.
5093+
5094+For docx output, styles will be defined in the output file as inheriting
5095+from normal text, if the styles are not yet in your reference.docx.
5096+If they are already defined, pandoc will not alter the definition.
5097+
5098+This feature allows for greatest customization in conjunction with
5099+[pandoc filters]. If you want all paragraphs after block quotes to be
5100+indented, you can write a filter to apply the styles necessary. If you
5101+want all italics to be transformed to the `Emphasis` character style
5102+(perhaps to change their color), you can write a filter which will
5103+transform all italicized inlines to inlines within an `Emphasis`
5104+custom-style `span`.
5105+
5106+For docx output, you don't need to enable any extensions for
5107+custom styles to work.
5108+
5109+[pandoc filters]: http://pandoc.org/filters.html
5110+
50645111Input
50655112-----
50665113
@@ -5109,49 +5156,6 @@ With these custom styles, you can use your input document as a
51095156reference-doc while creating docx output (see below), and maintain the
51105157same styles in your input and output files.
51115158
5112−Output
5113−------
5114−
5115−By default, pandoc's docx and ICML output applies a predefined set of styles
5116−for blocks such as paragraphs and block quotes, and uses largely default
5117−formatting (italics, bold) for inlines. This will work for most
5118−purposes, especially alongside a `reference.docx` file. However, if you
5119−need to apply your own styles to blocks, or match a preexisting set of
5120−styles, pandoc allows you to define custom styles for blocks and text
5121−using `div`s and `span`s, respectively.
5122−
5123−If you define a `div` or `span` with the attribute `custom-style`,
5124−pandoc will apply your specified style to the contained elements. So,
5125−for example using the `bracketed_spans` syntax,
5126−
5127− [Get out]{custom-style="Emphatically"}, he said.
5128−
5129−would produce a docx file with "Get out" styled with character
5130−style `Emphatically`. Similarly, using the `fenced_divs` syntax,
5131−
5132− Dickinson starts the poem simply:
5133−
5134− ::: {custom-style="Poetry"}
5135− | A Bird came down the Walk---
5136− | He did not know I saw---
5137− :::
5138−
5139−would style the two contained lines with the `Poetry` paragraph style.
5140−
5141−For docx output, styles will be defined in the output file as inheriting
5142−from normal text, if the styles are not yet in your reference.docx.
5143−If they are already defined, pandoc will not alter the definition.
5144−
5145−This feature allows for greatest customization in conjunction with
5146−[pandoc filters]. If you want all paragraphs after block quotes to be
5147−indented, you can write a filter to apply the styles necessary. If you
5148−want all italics to be transformed to the `Emphasis` character style
5149−(perhaps to change their color), you can write a filter which will
5150−transform all italicized inlines to inlines within an `Emphasis`
5151−custom-style `span`.
5152−
5153−[pandoc filters]: http://pandoc.org/filters.html
5154−
51555159Custom writers
51565160==============
51575161