Several months ago, I started utilizing Pandoc for generating EPUB documents. My eventual hope was to generate polished-looking books from Markdown source, enhanced by custom cover art and styles.

I began to notice difficulties making non-trivial style changes that were robust across readers and might be hoped to be stable over successive versions of Pandoc. I noticed also that even certain trivial changes were more difficult than might be reasonably desired.

The EPUB template and writer for Pandoc appear to be still in a relatively early state of maturity. Adding desired style depends largely on discovering the document structure of the output by examining it directly. The output is not globally structured according to a cogent and consistent design that is friendly to someone trying to add sophisticated or even moderately complex styling. Development efforts and users' understanding might be productively guided by a planned and documented design of how best to permit creation of style sheets that are robust and stable, yet simple and clear.

It was apparent to me that the best way to pursue this end was to introduce into the output a well-defined set of class tags, such that desired document elements could be easily selected by rules in style sheets. However, a broader set of considerations surround this issue.

I opened a discussion [1] in the issue tracker, and though it has received responses from John MacFarlane and another, it still lacks a breadth of responses necessary to determine which particular strategies might most compellingly serve those affected by the issue.

If you are affected by the issue, might benefit from enhancements related to it, have valuable experience in CSS or EPUB, or are otherwise in a position to provide useful opinions, please share your ideas. Your contributions would be appreciated.

1. https://github.com/jgm/pandoc/issues/5749