The MOBI format has the ability to associate an image with an index (TOC) entry which, if present, will be scaled and displayed by Kindle in the TOC list view. Amazon-generated periodicals make use of this and I would like to extend recipe functionality to allow recipes to optionally add an image reference to articles.

The easiest way to do this would be to use populate_article_metadata to scan the processed article, extract the url of an image to reference in the index (if there is such an image), and store that somewhere where MobiWriter can retrieve it. Any other output writer could make use of this or (by default) ignore it by not accessing the references.

I'm not familiar enough with the transition from input to conversion to output to be able to see where the references could be stashed for retrieval by an output writer. Is the OEB representation all on disk between input and output, or is there an in-memory representation of the article metadata that could be extended to include index image references? Can someone point me in the right direction?

That will require rather a lot of changes to various parts of calibre. To start with you would have to add a image_href attribute to the Article class and populate it with the value of the src attribute of the correct img tag in populate_article_metadata (you would have to make the link relative the the top level directory of the oeb book). Then change metadata/toc.py to support image_href, then change the TOC class in oeb/base.py then the _toc_from_navpoint() method in oeb/reader.py and finally MobiWriter.

def add_toc_thumbnail(self, article, src):
'''
Call this from populate_article_metadata with the src of an img tag you want to
appear as a thumbnail image in the articles list view of the table of contents
(Kindle feature)
'''
article.toc_thumbnail = re.sub(r'^.*feed','feed',src.replace('\\','/'),flags=re.IGNORECASE)