Custom styles for ODT (and maybe LaTeX and RST) writers

[matthijskooijman]

Currently, you can customize formatting by providing some customized styles in a reference odt/docx file to pandoc. These styles are copied into the generated document and applied to selected elements in the document.

However, this only supports a limited, hard-coded list of styles. E.g. the 'Heading 1' style is applied to level-1 headings, the 'Text body' style to regular paragraphs, the 'Bullet Symbols' style to bullets. On top of this, I'd like to be able to specify other styles to use, on a block-by-block basis.

My usecase is that I'm writing a book, and my publisher requires the text to be delivered in docx or odt format, using a set of custom styles with non-standard style names. I have two challenges:

1. Regular styles have different names, so I need to use e.g. "Publisher Heading 1" for first-level headings.
2. Some parts of my document must use completely different styles, which have no equivalent in the pandoc AST (e.g. notes for the layouter must use the "Layout Notes" style).

If I have some way to specify custom style names in the AST, I can use a pandoc filter to introduce the proper style names in the AST and have the writers use the right styles. Ideally, I'd be able to specify the style names for challenge 2 above directly in my markdown source.

Attributes seem like a good fit for this, so that would work out to something like this in markdown:

# My Header {style="Fancy Header 1"}

Note that this is already supported by the current markdown parser, and results in this JSON:

[{"unMeta":{}},
 [{"t":"Header","c":[1,["my-header",[],[["style","Fancy Header 1"]]],
 [{"t":"Str","c":"My"},{"t":"Space","c":[]},{"t":"Str","c":"Header"}]]}]
]

However, converting this to ODT or DOCX drops the attributes completely.

I'm aware that not all elements currently allow specifying styles, but that's another discussion. What I'd like to see is that, for all elements that currently support attributes, the "style" attribute be interpreted as a style name in the ODT and DOCX writes.

ODT and DOCX have a distinction between paragraph and character styles, but it seems that using the paragraph styles for block elements and character styles for inline elements is sufficient?

Does this sound reasonable? Is the "style" attribute the right fit here? For the HTML writer, the style attribute should contain a bit of raw CSS. I don't think we can have a single syntax that works for both HTML and ODT/DOCX, though perhaps we can have something that allows specifying two distinct attributes to allow working with both? At first glance, the class is more appropriate than an attribute, since a class is also a name that indirectly specifies formatting to be used. However, a class can be specified multiple times, which I don't think is applicable to DOCX / ODT styles? Or perhaps just use the first / last class name specified?

I'll likely spend a bit of time implementing this for my own needs, but I'd rather know up-front if this has any chance of being merged.

@mpickering, It seems that such a style= attribute could perhaps also be used by an asciidoc reader to fix #1234 / #1235.

[gbjbaanb]

It is possible to alter the styles in the docx after the generation is complete. For example, here I set the style for all tables to BlueTableStyle (which is a style in the template dotx I use to generate docx from pandoc). The styles are contained in the document.xml file inside the docx archive.

Obviously this is not an ideal solution and being able for pandoc to spit out the desired style name given the right directives would be great, similar to how you can specify them for HTML. I don't see why they would need different input syntax, the use-case for generating different styles based on output type is a can of worms best left closed.

7z x -y %~1.docx word\document.xml 
sed "s/<w:tblStyle w:val=\"TableNormal\"/<w:tblStyle w:val=\"BlueTableStyle\"/g" word\document.xml > word\document2.xml
copy word\document2.xml word\document.xml /y
7z u -y %~1.docx word\document.xml

[krtek4]

I am in the exact same situation : writing a book and the publisher insists on docx file format using their custom styles.

Is there any chance this could get implemented ?

The workaround proposed works really great when you want to style all given elements the same way, or rename a given style to some other one. But when just some elements needs to use a specific style I don't see how it can be made to work.

Thanks !

[matthijskooijman]

@krtek4, I ended up using docutils's rst2odt tool with the --odf-config-file and --stylesheet options to customize the output styles, which ended up suiting by needs just enough (with a few minor customizations to better handle images, code, etc.). I haven't found time to clean up my build process well enough to publish it, but if you're interested I can do a quick sweep, tar it up and send it to you. If so, drop me an email to not further pollute this issue.

[josdirksen]

I'm writing a book for Packt, which also uses a crappy docx template. I'm now using pandoc to convert my markdown file to docx, and afer that use a couple of XSLT steps to convert the styles from pandoc to the styles required by the template from Packt. This seems to work ok for the styles I'm currently using (basic bullets, lists, images etc.)

I haven't needed tables yet, but that should also be doable I guess. If you're interested let me know.

[krtek4]

Hi @josdirksen,

Finally I am use rst2odt like @matthijskooijman suggested. The tool allows for custom mapping from node types to ODT styles. For now I am able to manage with that quite well.

Hadn't thought of XSLT at the time, but that is also definitively a great idea :) Good continuation with your book.

[mb21]

Is this request fulfilled with http://pandoc.org/MANUAL.html#custom-styles-in-docx-output ? (at least for docx)

[krtek4]

As far as I can tell, this is exactly what is needed for docx. It is really similar to the feature I am using in rst2odt

[mb21]

Since this feature was implemented in docx, we might think about doing the same for ODT, ICML and maybe LaTeX and RST writers...

[matthijskooijman]

From a quick glance at the docs, I think what I requested in this issue would be made possible with that new feature. However, I've long since finished writing my book, so I have no specific interest in this feature anymore, so feel free to close this issue (or leave it open if someone else wants to do actual testing of the feature and report back).

[simongareste]

@mb21: I am very much interested in this for odt, and available to test.

[mb21]

@simongareste Personally, I'm not too familiar with the ODT format... feel free to take a look at the writer generating the OpenDocument format and the one packaging it into a .odt zip, pull requests welcome!

[marcban]

Unfortunately I'm not a Haskell developer, but here are some specs to help a little:

• source md file : this is a <span custom-style="mystyle">custom style span</span>
• in content.xml part of .odt file, this should generate:

<text:p text:style-name="Text_20_body">
  this is a <text:span text:style-name="mystyle">custom style span</text:span>
</text:p>`

• in styles.xml part, this should add a style (if not present) under <office:styles> tag, with value:

<style:style style:name="mystyle" style:family="text">
	<style:text-properties fo:font-weight="bold"/>
</style:style>

I propose that the custom style is bold by default, so that it will be visible in the output. Of course, by using a custom template, the user can define his own style.

[mb21]

I'm reposting here some discussion from the now closed #2542

+++ Mauro Bieg [Dec 31 15 09:38 ]:

In LaTeX those divs/spans could be rendered as custom
environments/commands. This was actually proposed by hadley in
#168 (comment), or do you think the concepts are not analogous enough?

+++ jgm:

I want to avoid generating environments and commands that
aren't defined (and similarly for styles in Word and ICML).
If we parse the styles, and thus know what is available,
that may not be a big problem. In LaTeX it's harder,
because commands and environments may be defined in
included packages. The idea of having a special prefix
like style- might be a good one.

Since the following already works for docx output:

::: {custom-style=poetry}
My example poem,
is bad.
:::

the idea is to change the syntax (and probably AST representation) to use a class with the style- prefix:

::: style-poetry
My example poem,
is bad.
:::

and make it work for ODT and ICML (and maybe even LaTeX and RST) as well (although for RST output, pandoc already uses the role attribute). For example LaTeX output:

\begin{poetry}
  My example poem, is bad.
\end{poetry}

[ghost]

Writing custom-style everywhere a custom style is required is redundant and differs in behaviour from HTML output. Consider:

::: {.projection}
    Executing reverse bias polarity on neurowafer 1 of 7.
    Estimated time remaining: 3h 39m 57s
:::

Thanks to #168, this produces the expected output:

<div class="projection">
<pre><code>Executing reverse bias polarity on neurowafer 1 of 7.
Estimated time remaining: 3h 39m 57s</code></pre>
</div>

However, when the output is ConTeXt, this produces the astonishing result:

\starttyping
Executing reverse bias polarity on neurowafer 1 of 7.
Estimated time remaining: 3h 39m 57s
\stoptyping

I consider it astonishing because the {.projection} class is swallowed, silently, instead of being retained in some manner, such as:

\starttyping[class=projection]
Executing reverse bias polarity on neurowafer 1 of 7.
Estimated time remaining: 3h 39m 57s
\stoptyping

Since pandoc cannot presume environments exist, it would be convenient if there was a command line argument that indicates that they do. Consider:

pandoc -t context --tex-environments --top-level-division=chapter file.md -o file.tex

Here, the --tex-environments option indicates that the developer (author) has created the required environments and that pandoc can use them. For ConTeXt, this could resemble:

\startprojection
\starttyping
Executing reverse bias polarity on neurowafer 1 of 7.
Estimated time remaining: 3h 39m 57s
\stoptyping
\stopprojection

Returning to the HTML output, if the source document contains:

::: {.style-projection}
    Executing reverse bias polarity on neurowafer 1 of 7.
    Estimated time remaining: 3h 39m 57s
:::

This would produce:

<div class="style-projection">
<pre><code>Executing reverse bias polarity on neurowafer 1 of 7.
Estimated time remaining: 3h 39m 57s</code></pre>
</div>

Clearly, the style- is superfluous and would only be necessary because there is no other way to coerce pandoc into generating LaTeX/ConTeXt environments. IMO, a command line argument would allow the Markdown document to be written as per the author's descriptive intent, without being encumbered with knowledge of the internal workings of pandoc (that is, how it treats Markdown differently depending on whether the output is HTML or TeX).

WDYT? @adityam? @jgm?

[jcbagneris]

Hello there,

I do agree that it would be convenient to have a way to tell pandoc "create an environment, I know what I am doing" but instead of a general option, I guess that an extension would be more adapted.

Something in the line of:

pandoc -f markdown -t latex+create_envs

That would allow for the extension to be output dependent, which is probably needed.

Fenced divs are great, let's make good use of those :)

Thanks

[ghost]

An extension would also work, though my preference would be for slightly different names:

pandoc -f markdown -t context+environments
pandoc -f markdown -t latex+environments

[jcbagneris]

Ah, I just meant to advocate for extension vs. option. I don't really care about the name, provided it's meaningful. +environments is ok for me.

[mb21]

In order to use the fenced div class syntax for custom-styles, the user has to specify his intent to use the div as such an environment - either by switching on an extension (e.g. +environment) or using a prefix like style- on the class.

The prefix is more verbose, but also more explicit: you then could have multiple divs in the same document and have only some converted to custom-styles aka environments. The writers could then strip the style- prefix when creating the style name. Do you think writing style- a few times is so bad?

[iandol]

On the duplicate #4139, I had asked for just a simple translation from ::: style ::: to a paragraph style in a format such as DOCX. The argument here is that to make this universal across other writers like LaTeX, an implicit conversion is not preferred by @jgm (although implicit conversion is the default for HTML presently). So the current options are to manually enable a universal mechanism (via either style- in the document or a +environment).

A third option is that this could depend on the writer, implicit for ODT/DOCX/HTML, explicit for LaTex and friends that change the actual output structure. I suspect this is also not preferred by @jgm, but Pandoc already has implicit HTML support and I think a div.class is semantically identical to a paragraph.style which is why the implicit rule could be extended to this type of document structured output...

[ghost]

Do you think writing style- a few times is so bad?

Yes. It's redundant, verbose, inconsistent, and assumes pandoc-specific implementation knowledge. (Aside, there's no way to know how many times a style will be used in a given document.)

The writers could then strip the style- prefix when creating the style name.

Seems to violate the KISS principle: it incurs extra work (post-processing) to strip the prefix. Simpler (for writers) to not use or require a prefix altogether.

[mb21]

@DaveJarvis but you agree that the toggle-by-extension-approach has the disadvantage that in one document, you cannot use some divs for custom-styling while using other divs for other purposes, right?

[ghost]

you cannot use some divs for custom-styling while using other divs for other purposes

There can be options for both scenarios. For example, the custom styles could be explicitly listed once on the command line (or read from an external data source), rather than repeated throughout the text, freeing the unlisted div demarcations for other purposes. Or, depending on what list is shorter, an option to list the unstyled divs may be useful.

Also, a style- prefix suggests that the class is used for style-ing, which hints at presentation logic. As you pointed out, classes can be used for more than styling. Whether and how content marked with classes is styled or otherwise manipulated belongs outside of the document.

$ pandoc --styled poetry,stanza,prose ...
$ pandoc --styled-file styled.txt ...
$ cat styled.txt
poetry
stanza
prose
$ pandoc --unstyled foo,bar ...
$ pandoc --unstyled-file unstyled.txt ...
$ cat unstyled.txt
foo
bar

[mb21]

So we have three options now (the exact naming/implementation is also still debatable):

• mark up divs with style- prefixed class
• +environments extension that would tell pandoc to treat all divs as custom-styled-environments
• --styled argument that lists all divs to be styled

I'd like to get some feedback from more people on which of the three they prefer... @jgm?

[jkr]

I think I prefer (a) explicit over implict, and (b) not having to change the command-line every time you change the source file (or consult a long file as reference for the sake of constructing a command line). For those reasons, FWIW, I guess I like the first option (style-) and pretty strongly dislike the others.

• I think +environments could have major side-effects in moving to word-processing docs, where you might not even know the names of all possible styles in your reference file.

• Keeping a list of all environments to be made into a custom style seems overly difficult to maintain. I can't think of another place in pandoc where the user has to specify content from within the document on the command line.

So -- style- seems the best of the three. Perhaps the least elegant, but more easier to use and maintain precisely for that reason.

BUT I'm not sure I see why style-* is preferable to custom-style=* (or some shorter key-value attr, style=*). It saves a few keystrokes, and replaces an = with a hyphen, at the expense of parsing values, and essentially creating an inconsistent ad-hoc syntax for certain class attributes. It's not a big deal, but it seems a bit more obscure for not that much gain.

[ksesong]

I've been trying to build a filter for ICML writers based on @jzeneto's custom filter, but I can't find a way to make it work.

We essentially have to substitute the default <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph"> with the custom version <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/{style}">, and add another entry in the <RootParagraphStyleGroup> (page 36 for reference) for each custom style.

Is this feasible with custom filters?

[mb21]

@ksesong It turned out that it's actually quite easy to do in the ICML writer itself. See #5137...

[kprussing]

From the LaTeX output perspective, one problem with converting the class to an environment is: inevitably someone will want to pass arguments (positional, optional, and potentially keyword) to the environment. I don't see how to specify those arguments in a way that would not interfere with other writers. We already have a few examples of filters for LaTeX to convert the class to to an environment, and I've been playing with a filter that uses data attributes to pass the environment and arguments. To me, this seems more like a problem for filters and explicit markup than the core readers.

[gpongelli]

Hello, thanks for this awesome tool !!

Is there a way to set a custom style information in a Latex input file and have it into the output odt, similar to what's done here with markdown input ?

Or also something (filter and so on) that's able to catch dummy Latex commands at reader side like this

\newcommand{bluestyle}[1]{#1}
...
\bluestyle{I'm blue}

to be converted in a markdown block

::: {custom-style="bluestyle"} 
I'm blue
:::

to be able to reuse the odt custom styles repository already created (reaching the same result with two step conversion latex->markdown->odt).

I've tried the Latex \texcolor without any useful result on odt output file even if it's recognized (no errors were thrown).

Thanks!

[niszet]

Maybe a bit out of track, custom styles for ODT has been implemented by this commit. And this can be used from Pandoc 2.10.

bde3d76

So, LaTeX and RST writers don't have custom styles now?

I would like to share this update information who are searching custom styles for ODT.

[Migsi]

Hello, thanks for this awesome tool !!

Is there a way to set a custom style information in a Latex input file and have it into the output odt, similar to what's done here with markdown input ?

Or also something (filter and so on) that's able to catch dummy Latex commands at reader side like this

\newcommand{bluestyle}[1]{#1}
...
\bluestyle{I'm blue}

to be converted in a markdown block

::: {custom-style="bluestyle"} 
I'm blue
:::

to be able to reuse the odt custom styles repository already created (reaching the same result with two step conversion latex->markdown->odt).

I've tried the Latex \texcolor without any useful result on odt output file even if it's recognized (no errors were thrown).

Thanks!

Did you find a way to accomplish this? We are currently encountering almost the same issue, but our output is docx. /textcolor commands seem to be ingested just fine, but don't produce any meaningful ouptut (yet?), so we tried the custom styles approach, failing on how to define the required attributes in the first place.
Intrestingly enough, while playing with markdown as input, we found that the chosen style is never applied properly. Instead the "formatted" piece of text recieves a new style, named 1:1 as the chosen custom style + a seemingly random number. Thus we were never able to apply a custom style even when following the docs.

[jgm]

Intrestingly enough, while playing with markdown as input, we found that the chosen style is never applied properly. Instead the "formatted" piece of text recieves a new style, named 1:1 as the chosen custom style + a seemingly random number. Thus we were never able to apply a custom style even when following the docs.

This sounds like a bug. Why don't you submit a new issue about this, with a minimal sample and complete instructions for reproducing?

[Migsi]

Intrestingly enough, while playing with markdown as input, we found that the chosen style is never applied properly. Instead the "formatted" piece of text recieves a new style, named 1:1 as the chosen custom style + a seemingly random number. Thus we were never able to apply a custom style even when following the docs.

This sounds like a bug. Why don't you submit a new issue about this, with a minimal sample and complete instructions for reproducing?

I misunderstood a colegue of mine, ignore that part. Though we are still intrested in getting custom styles in latex -> docx conversion working.

[niun]

Maybe a bit out of track, custom styles for ODT has been implemented by this commit. And this can be used from Pandoc 2.10.

bde3d76

Unfortunately, I don't quite understand the Haskell code. Do I understand it correctly that spans or paragraphs with the attribute "custom-style" should be rendered in the target ODT document with the character or paragraph style given with this attribute?

Should the ODT writer create this style in the target document? Despite everything I tried, this does not seem to happen for me.

I have tried several things, the "custom-style" attribute appears with its value in the "native" format of pandoc but I can't find it in the styles.xml and content.xml. Even if I specify a style that is present in the reference document, it is not applied to the particular <text:p> or <text:span> element.

For example I have this in my Markdown file:

Some Text, [StyledTestText]{custom-style="MyStyle"}, and boring stuff after.

The "native" output of pandoc gives me:

 , Para
      [ Str "Some", Space, Str "Text,", Space
      , Span
          ( "" , [] , [ ( "custom-style" , "MyStyle" ) ] )
          [ Str "StyledTestText" ]
      , Str ",", Space, Str "and", Space, Str "boring", Space, Str "stuff", Space, Str "after."
      ]

But when running

pandoc  --reference-doc=reference.odt -f markdown -t odt -o testdoc.odt testdoc.md

in content.xml of testdoc.odt there is only

<text:p text:style-name="Text_20_body">Some Text, StyledTestText, and boring stuff after.</text:p>

Do I need to enable rendering of custom-styles somehow or is this a bug or am I understanding everything wrong?

By the way:

$ pandoc --version
pandoc.exe 2.18
Compiled with pandoc-types 1.22.2, texmath 0.12.5, skylighting 0.12.3,
citeproc 0.7, ipynb 0.2, hslua 2.2.0
Scripting engine: Lua 5.4
...

[iandol]

Indeed @jgm states that commit should allow it to work: bde3d76#commitcomment-39238082 — but with my ignorance of Haskell it sure does look like it is specific to Abstract metadata...

The docs suggest only DOCX and ICML support custom-style: https://pandoc.org/MANUAL.html#custom-styles

EDIT: however the changelog for 2.10 shows custom-style support as added to the OpenDocument writer...

[iandol]

@niun — I just tested from the command line:

ⓔ ▶︎ pandoc -t odt -o out.odt
# This is a test

A first paragraph.

Another.

::: {custom-style="Sender"}                
This should be Sender style.
:::

Another.

::: {custom-style="SenderXYZ"}                
This will not work as not present.
:::

Final.

And out.odt does have the Sender style applied. Are you sure you modified the reference odt to have the Style you are specifying? Sender is built-in and at least it is working; SenderXYZ was not present in the reference and so ends up with default paragraph style...

[iandol]

The other issue I think is that this only works for block paragraphs, not inline styles?

[niun]

@iandol -- thanks for testing this.

Now I did some additional tests and yes, inline styles are not supported and for the paragraph style, I used the example from the pandoc manual.

Which looks like this:

Dickinson starts the poem simply:

::: {custom-style="Poetry"}
| A Bird came down the Walk---
| He did not know I saw---
:::

I was not aware that the vertical bars at the start of the line are creating a line block which seems also not to be supported for custom styles with the ODT writer.

So if the style is in the reference document (does not matter if built-in or custom) and the text is a normal paragraph (annotated with "fences"), than the custom styling is working. @jgm custom inline styles for ODT writer would be a real treat. Or is there some working way of annotating inline styles, I am not aware of?

[iandol]

I don't know of another markup syntax that works, and yes it would be great to extend the already supported block syntax to the inline case.

[jgm]

I'm going to close this issue, which is too diffuse.
I've just implemented custom styles for spans in ODT.