Annotations: HTML Output & eBook format selector

[yogat3ch]

Hello Calibre Developers,

I'm joining this forum to discuss a potential enhancement for the Annotations/Highlights/Notes viewer and exporter within Calibre. My goal is to add a GUI selection for the eBook format when viewing or exporting annotations.

I'm currently using Calibre for a Dharma Teacher Training program and making extensive highlights and notes. I've developed a JavaScript function (Node.js) that combines Calibre's annotations with Markdown to create a more robust HTML output, preserving highlight colors and clearly distinguishing between notes and highlights. You can find the code on my new repository here.

During this process, I've consistently encountered an issue where it's unclear which eBook format's annotations are being exported when multiple formats (e.g., EPUB and PDF) are associated with the same book. This makes it difficult to manage and verify annotations from specific versions.

My intent is to develop a feature that allows users to select the specific eBook format from which annotations should be displayed and exported in the GUI. I believe this would significantly improve the usability and precision of Calibre's annotation features.

Seeking Collaboration
I'm looking for assistance and guidance from experienced Calibre developers. While I have a background in R and JavaScript, and some familiarity with Python, I'm new to the specifics of Calibre's codebase, particularly its annotation export engine and APIs.

If you have insights into:

Calibre's Python architecture for handling annotations and eBook formats.
The best approach for adding a GUI element for format selection.
Integrating external tools or scripts (like my HTML output function) into Calibre.
Please reach out! I'm eager to contribute and collaborate on implementing this feature.

[kovidgoyal]

Why not just use different book records for your two files instead.

[yogat3ch]

Originally Posted by kovidgoyal

Why not just use different book records for your two files instead.

Thank you for the response Kovid! I suppose that could offer a workaround. However, I have 100+ highlights in the PDF and 50 or so highlight/notes in the epub already. I think create a new entry would also create a duplicate folder structure and would require the metadata copied over.
Given Calibre already has the ability to select the format when viewing a book, it seems like a simple dropdown with the available formats on the highlight screen could solve this problem.

Do you have a sense of the process to implement a dropdown on the highlight viewer?

[kovidgoyal]

Annotations are stored in the EPUB file by default. So simply add the epub file again to your library and you will get all the annotations from a separate book record. And if you want to export annotations from a particular format you can do so via the calibre viewer, by opening the highlights side panel and clicking export.

I am not going to accept a control in the annotations browser for a per format export as its a niche use case already covered by exporting via the viewer.

[yogat3ch]

Originally Posted by kovidgoyal

And if you want to export annotations from a particular format you can do so via the calibre viewer, by opening the highlights side panel and clicking export.

Ahh, I had not noticed that there was an export button within the highlights window of the viewer! Thank you for that tip, that definitely solves the issue.

Did you happen to see the JS function that makes an HTML version of the Highlight/Note output that was linked in my initial post? Do you think that would be a useful addition to Calibre?

[kovidgoyal]

Sure you are welcome to contribute code to output in HTML format, but it will need to be in python not JS.

[yogat3ch]

Originally Posted by kovidgoyal

Sure you are welcome to contribute code to output in HTML format, but it will need to be in python not JS.

Ok, I'll see about reworking it in Python first for a proof of concept. Can I circle back once I've got a working Python function to ask some questions about how to integrate it?

[yogat3ch]

Update: I've created a Python version that uses the Markdown export and Calibre Annotations JSON to create an HTML file which can be found here. I noticed the cmd_export.py in the repository but it appears to be for exporting books. Can you provide some pointers for how to orient to the codebase to integrate this? I've used Python for browser automation for web app automated testing and haven't had experience building desktop applications with Python so it may take me some time to understand the Python desktop application framework and the file structure of the codebase.

[kovidgoyal]

relevant code is in src/calibre/gui2/viewer grep for export and markdown to find it.