I want to display chapter and section headings in an epub file (epub version 3.0) so that the titles preceded by the corresponding section numbers. Currently I am explicitly writing the section numbers inside the corresponding HTML tags:

<h1>1 Exciting Concepts</h1>
<h2>1.1 Introduction</h2>
<h2>1.2 Buildup to Excitements</h2>

To my eye, this approach seems somewhat ugly, because the numbers are not really part of the chapter/section titles and including the numbers in the header tags may violate the separation between content and presentation.

My questions:

  1. Will my approach cause any problems? For example, are ebook readers guaranteed to not add their own chapter/section numbers?

  2. Is there a better way to display numbered sections? For example, I found tutorials for adding automatic section numbers to HTML via CSS, but it is not clear to me how will work when the text is split between different HTML files, and whether there are compatibility concerns with ebook readers.

  • 2
    Perhaps you should review your overall writing process. Are you writing a book in pure HTML? I write in markdown and use Pandoc to create an EPUB, which should do this numbering automatically, PLUS generate a TOC for you. Pandoc supports several flavors of Markdown, plus some extensions, and I love it.
    – Bulrush
    Commented Aug 16, 2017 at 18:27

3 Answers 3


EPUB3 defines a profile for CSS which is pretty much a superset of CSS 2.1 and a subset of CSS 3.

I haven't checked to see whether the CSS facilities mentioned are covered in the profile, but if they are it will then depnd on how well those are implemented in particular readers.


First, that tutorial was interesting and useful. But I don't think that CSS is supported in kindle https://www.amazon.com/gp/feature.html?docId=1000729901 or epub. I could not even find that css in the epub3 support grid http://epubtest.org/features/ (which may or may not mean something). That sounds like the sort of thing which Google Play Books MIGHT support though I'd want to verify.

Second, my method for producing epub accomplishes exactly what you want. I am using Docbook XML (and Docbook XSLT) to generate XHTML output which I then zip and validate. It's not an easy solution and it is very tricky, but Docbook has much more semantically rich elements and some powerful ways to style it. It includes various different methods for changing the numbering for sections (and even omitting the numbering). It also has different methods for chunking the output by chapter/section/subsection.

http://www.sagehill.net/docbookxsl/HtmlOutput.html Unfortunately documentation for producing epubs is not up to date. (In fact, it just occurred to me that I should write up a tutorial about my own process).

While Docbook may require too much learning curve for your current task, its approach illustrates how to solve the problem in another way.

With regard to your specific need, I think it's perfectly valid to hardcode numbering into your sections -- even if it will be hard to maintain over time. Sometimes the dumb solution is still the best. You could use a media query to separate between reading systems that support the css and those that do not. (But that could be messy if you need to change the content and not just the presentation).

This raises another question. Wouldn't you want the TOC to reflect the numbering as well? Yes, it's possible to have different levels in your TOC. The excellent book Epub3 Best Practices by Matt Garish covers topics like that -- although it doesn't go into detail about css support -- which is still a moving target. (I suspect that Oreilly is also using Docbook behind their production process as well) http://shop.oreilly.com/product/0636920024897.do


You should do it either as you do now, manually, or automated as part of the writing process using markdown, docbook etc, the reason being that most hardware readers are rarely up-to-date. Readers that can be updated with new firmware are not necessarily so by their users (some people use Windows XP even in 2018), and those that can't be updated for some reason aren't replaced when a new EPUB standard comes along.


  • Are ebook readers guaranteed to not add their own chapter/section numbers?
    – jochen
    Commented Jul 12, 2018 at 18:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.