What the RichEPub Toolchain Actually Taught Me

The original RichEPub toolchain was built around a custom .repub package. In practice, that was not the part worth optimizing.

What mattered was the pipeline thinking behind it:

• author from real working material instead of idealized clean input
• preserve structure while moving between tools
• let design decisions be explicit instead of accidental
• export to something stable enough to survive outside one custom reader

That last point is where the custom format fell apart for me. EPUB3 is already good enough for most of the document and packaging layer. The harder problem is preparing content well enough that the EPUB looks intentional when it gets there.

The real pipeline problem

Books can start almost anywhere:

• Notion exports
• markdown folders
• MDX files
• partially structured drafts with images and ad hoc formatting

Supporting those inputs cleanly is harder than inventing a zip file with a manifest. The expensive part is normalization, layout control, and export discipline.

What I would build instead

If this system keeps growing, the better direction is a writing and layout tool that compiles to EPUB3.

The rough shape would be:

1. import uneven source material
2. normalize it into a structured document model
3. let the author apply richer layout and component choices in a controlled UI
4. compile the result down to EPUB3-safe markup, assets, and metadata

That could still use React and Node for the toolchain. It could still use component ideas. It just does not need a new reader-facing format to justify itself.

Why I am not rushing to build it

Even that editor path might be more hassle than it is worth.

The value only appears if it meaningfully reduces cleanup, improves layout quality, and keeps the export stable. Otherwise it becomes another custom system that mostly recreates problems other tools already solve well enough.

So the current stance is simpler:

• keep the books pipeline focused on EPUB3
• keep the old RichEPub notes as archive material
• plan the editor carefully before pretending it should exist

That planning now lives in the docs as its own section, because the editor is a tooling problem first, not a format-spec problem.