Inside the Head of PyDanny

Hi, I'm Daniel Roy Greenfeld, and welcome to my blog. I write about Python, Django, and much more.

Generating NCX files with Python

With the help of fellow Python developer Matt Harrison's excellent Ebook Formatting: KF8, Mobi & EPUB, we managed to create pretty decent looking Kindle and ePub versions of Two Scoops of Django.

One of many things we did was focus on providing an excellent table of contents. Of course we provided one inside the content of the book, but much like the PDF version we also provided one that various ebook readers can display in sidebars or drop down menus. Unfortunately, building this navigation isn't well documented (except for Matt's book), and I've yet to see any good ways to generate it via code.

Which is why I present the following code. It looks at the HTML that KindleGen and ePub generators demand and pulls from it a chapter-based table of contents. Then constructs a .ncx file, which is what ebook readers use to generate the sidebar/dropdown table of contents.

Our requirements:


And now the code:

# -*- coding: utf-8 -*-

from bs4 import BeautifulSoup
from django.utils.text import slugify
from jinja2 import Template

TEMPLATE = Template("""<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN" "">
<ncx xmlns="" version="2005-1" xml:lang="en">

<!-- The content of dtb:uid must be exactly the same as the uuid specified in the OPF file. -->

<meta name="dtb:uid" content="urn:uuid:BLAH-BLAH-BLAH"/>
<meta name="dtb:depth" content="1"/>
<meta name="dtb:totalPageCount" content="0"/>
<meta name="dtb:maxPageNumber" content="0"/>

<docTitle><text>Two Scoops of Django: Best Practices for Django 1.5</text></docTitle>
<docAuthor><text>Greenfeld, Daniel</text></docAuthor>
<docAuthor><text>Roy, Audrey</text></docAuthor>
{% for chapter in chapters %}
<navPoint id="{{ chapter.slug }}" playOrder="{{ loop.index }}">
<navLabel><text>{{ chapter.string.strip() }}</text></navLabel>
<content src="{{ chapter.href }}" />
{% endfor %}

def main(filename):

    # Grab the base file for review
    with open(filename) as f:
        text =

    # load the text into a bs4 object
    soup = BeautifulSoup(text)

    # grab the nav element
    nav = soup.find("nav")

    # loop through the TOC for chapters. 
    # Sections/Subsections can't be displayed, so don't worry about them
    # li.chapter is how we constructed our TOC. Your mileage may vary.
    chapters = []
    for li in nav.find_all("li", "chapter"):

    # Render the template
    template = TEMPLATE.render(chapters=chapters)

    # convert to ASCII
    template = template.encode("ascii", "xmlcharrefreplace")

    # Save to the toc.ncx
    with open("toc.ncx", "w") as f:

if __name__ == '__main__':

There is more to adding a table of contents then just this simple module. You also have to construct the .opf file, which is another undocumented mess that I'll blog about.

Tags: python twoscoops book django howto


If you read this far, you might want to follow me on twitter or github and subscribe via email below (I'll email you new articles when I publish them).



Content Copyright © 2012-2018 Daniel Greenfeld. Proudly harnessed by Mountain, powered by Flask, and rendered by Frozen Flask, all of which take great advantage of Python.