專案筆記Json變成Epub
Use this skill when a project-note JSON or folder-derived JSON manuscript needs to become an EPUB, or an EPUB plus a PDF review/distribution edition, especially when the user wants chapter directories, index cards, cross-links, keyword numbering, versioned check editions, Chinese character counts, chapter-splitting plans, Kindle-clickable PDF links, or full EPUB/PDF link verification.
Chinese trigger phrases include:
專案筆記Json變成Epub目錄索引卡交叉連結把這章做成EPUB章節拆書關鍵字索引卡雙向連結EPUB同時生成PDFKindle可以點擊連結
Core Workflow
-
Inspect the JSON schema before generating anything.
- Identify
title,sources,toc,chunks,index, and validation fields if present. - Confirm each chunk has a stable code, title, body or source text, EPUB page/anchor, and Chinese character count.
- If the JSON is missing fields, derive them deterministically and write the enriched JSON first.
- Identify
-
Normalize the book identity.
- Use the user-provided book name exactly.
- For check editions, name versions as:
{書名} 檢查版 YYYY-MM-DD NN. - Use an ASCII-safe or underscore filename when needed:
{書名}_檢查版_YYYY-MM-DD_NN.epub. - Keep a simple
download.epubcopy for mobile sharing if the user needs an easy download link.
-
Build the table of contents from project-note numbers.
- Preserve Luhmann/Zettelkasten-style codes such as
1.1,3.3.c3b, and3.3.d.1. - Split into no more than five display levels: 部、章、節、項、目.
- Prefer original titles; generate compact titles only for unnamed chunks.
- Mark Chinese character counts at each level where possible.
- Treat the TOC as a directory card: every entry should preserve code, title, depth, page anchor, and future split-book key.
- Preserve Luhmann/Zettelkasten-style codes such as
-
Build the keyword index before EPUB rendering.
- Each keyword must have a stable id:
K001,K002, ... - Sort by descending weight, then keyword for deterministic order.
- Remove keywords below the requested threshold. If unspecified, ask or use the current project threshold.
- Each keyword may link to at most 5 target pages/chunks.
- Each index link needs display text, target, anchor, chunk code, title, and weight.
- Treat every keyword entry as an index card with id, keyword, weight, chapter attributes, selected page links, and cross-link metadata.
- Each keyword must have a stable id:
-
Add bidirectional link data.
- Forward link: index keyword page number ->正文 chunk anchor.
- Backlink:正文 keyword marker -> index keyword anchor.
- Use the keyword id as backlink display text, such as
K001. - Store backlinks in JSON on the chunk, for example
keyword_backlinks. - Preserve cross-link attributes on each link: chapter key, section key, item key, selected page order, base weight, remote bonus, adjusted weight, and selection rank.
-
Prepare chapter splitting data.
- Add a
book_split_planto JSON when the project is likely to become multiple chapter books. - Each split entry should include split key, title, first/last code, first/last page, chunk count, CJK count, and output filename hint.
- Keep this data orthogonal to the EPUB render so chapters can later be exported independently.
- Add a
-
Render EPUB paths relative to the XHTML file that contains the link.
- From
Text/index.xhtmlto正文 parts, usepart2.xhtml#p099, notText/part2.xhtml#p099. - From
Text/part*.xhtmlback to the index, useindex.xhtml#idx-k001, not../Text/index.xhtml#idx-k001. - Keep canonical JSON targets if useful, but convert hrefs correctly during XHTML rendering.
- Put the keyword index card at the end of the book spine as book back matter: directory/intro first,正文 chunks next,
index.xhtmllast. This matches normal human book structure where an index appears after the main text.
- From
-
Generate a PDF companion when requested.
- Use the same enriched JSON, TOC, chunk anchors, keyword ids, and backlink data as the EPUB.
- Preserve the same human link model: directory/index entries jump to正文 anchors, and正文 keyword markers jump back to keyword index anchors.
- Use PDF internal destinations and link annotations, not external file URLs, so links remain clickable after sideloading to Kindle.
- Prefer visible blue linked text for PDF review copies because Kindle users need a clear tap target.
- Embed a CJK-capable font when generating Chinese PDFs. Avoid relying on a viewer's fallback fonts; black square glyphs are a build failure.
- Keep PDF anchors semantically aligned with EPUB anchors when possible: chunk
p099in EPUB should map to PDF destinationp099, and keywordK001should map toidx-k001. - Treat PDF as a companion format; do not let PDF layout constraints mutate the canonical JSON or EPUB href rules.
-
Validate before delivery.
- Open the EPUB zip and parse every XHTML file as XML.
- Collect all
idanchors and allhreflinks. - Resolve every href relative to its source XHTML path.
- Fail the build if any target file or anchor is missing.
- Count expected forward links from
index[].links. - Count expected backlinks from
chunks[].keyword_backlinks. - Confirm actual EPUB forward/backlink counts match expected counts.
- Recalculate
true_body_cjk_countfrom正文 body/chunk text only, excluding TOC, index cards, navigation files, metadata, CSS, generated link labels, and markup. - Report the true body count separately from total EPUB or generated XHTML text counts.
- Confirm
orthogonal_check.okis true when the JSON includes directory/index/cross-link fields. - For PDF output, inspect the PDF annotations with
pypdfor equivalent and fail if internal GoTo/destination link counts do not match the expected forward/backlink model. - Render the PDF to PNG and visually confirm Chinese text, blue link text, spacing, and page flow. If Chinese text renders as boxes, fix font embedding and rebuild.
EPUB Requirements
- EPUB mimetype must be the first zip entry and stored uncompressed.
META-INF/container.xml,OEBPS/content.opf,OEBPS/nav.xhtml, and XHTML text files must exist.dc:titleincontent.opfmust match the requested book/version title.- The書末索引 must show keyword id, keyword, weight, and clickable page links.
- The OPF spine must place the keyword index page after all正文 pages unless the user explicitly requests a front-loaded index for review.
-正文 keyword markers should show the keyword plus a small clickable
Kxxxbacklink. - Preserve readable styling; backlinks should not disrupt paragraph flow.
PDF Requirements
- Generate PDF only when requested, or when the user asks for Kindle-compatible clickable links.
- PDF links must be internal document links using named destinations or explicit GoTo actions.
- The書末索引 must include clickable links back to正文 chunk destinations.
-正文 keyword markers must include clickable
Kxxxbacklinks to the keyword index destination. - PDF link counts should mirror EPUB expectations unless layout requires an explicitly documented exception.
- Use a CJK-capable embedded font for Chinese output. On macOS, a ReportLab build may use a TTC font such as
/System/Library/Fonts/STHeiti Medium.ttcwith a selected subfont index; in other environments choose an available Noto/Source Han CJK font. - Render at least one representative page to PNG before delivery and inspect for missing glyphs, clipped text, overlapping links, and unreadable spacing.
- Kindle note: PDF internal links are the compatibility target. Do not depend on JavaScript, web URLs, or EPUB-only href behavior for the PDF edition.
Validation Checklist
Before telling the user it is finished, report:
texterrors: 0 title: ... all_href_count: ... index_forward_links_tested: ... body_return_links_tested: ... index_entries: ... true_body_cjk_count: ... file type: EPUB document pdf_internal_links_tested: ... pdf_render_checked: ... pdf file type: PDF document
If any count fails, fix the generator and rebuild rather than editing EPUB output by hand.
Delivery
Return two links when possible:
- A simple mobile-safe link:
download.epub - The formal versioned EPUB filename
- The companion PDF filename when generated
- A validation report or short count summary when both EPUB and PDF are generated
Mention the version title and the link-test summary briefly.
