add a tool to create an epub

[wjhrdy]

You can run this with ./build_epub.py

assuming you have uv installed

[luongnv89]

Hi @wjhrdy,

Thank you very much for taking your time to add a script to generate an .epub version of this resources. I really appreciate that.

There is one issue (not very critical), so if you can address it, that would be great, otherwise just lets me know, I can accept this even without the fix.

Although there are few things not totally relate to the code itself:

• please create a new folder scripts/ and then move your scripts into
• update the comment on the header file of the script to provide instructions on how to use this script.

Thank you again

---

Found 1 issue:

1. Mermaid counter/cache bug: The global _mermaid_counter is incremented on every call including cache hits, causing cached images to get new UIDs each time. This results in the same image being added multiple times to the EPUB with different identifiers, wasting space and creating duplicate entries.

https://github.com/wjhrdy/claude-howto/blob/a737d687eba51b0e57ccc8af0e33be76d1eda207/build_epub.py#L30-L40

The counter should only be incremented when a new image is actually rendered, not on cache hits. Consider storing the filename along with the image bytes in the cache, or generating filenames deterministically based on a hash of the mermaid code.

[luongnv89]

Hi @wjhrdy ,
Thank you again for spending your valuation time to make the change. We are almost there, just one more push. Sorry to make you work back-and-forth, but we are aiming to have a good quality code. Here are something I (and Claude) have found out:

Binary file committed

claude-howto-guide.epub

Issue: The generated .epub file is committed to the repository. This is typically not recommended
since:

• It's a build artifact that can be regenerated
• It will cause unnecessary merge conflicts
• It increases repository size

Please: Add *.epub to .gitignore and remove the binary from the PR. The GitHub Actions workflow will create releases with the artifact.

Script path issue

  if __name__ == '__main__':
      root = Path(__file__).parent
      output = root / "claude-howto-guide.epub"
      create_epub(root, output)

Issue: The script sets root to scripts/ directory (where the script lives), not the repository
root. This will fail to find the markdown files.

Suggested fix:

  if __name__ == '__main__':
      root = Path(__file__).parent.parent  # Go up one level to repo root
      output = root / "claude-howto-guide.epub"
      create_epub(root, output)

Thank you again, I will merge as soon as these issues are addressed. I am really looking forward to make the first PR merge with you!

[wjhrdy]

Its all good, this is the process. Happy to contribute.

[wjhrdy]

How do you feel about just gitignoring the epub?

[luongnv89]

How do you feel about just gitignoring the epub?

that works for me