epub-hypercard-obsidian
Convert EPUB card books into Obsidian-ready HyperCard Markdown folders and portable zip files. Use when Codex needs to turn an EPUB with XHTML chapters, table-of-contents cards, keyword index cards, b
SKILL.mdskills/epub-hypercard-obsidian/SKILL.md
GitHubEPUB HyperCard Obsidian
Create an Obsidian folder from an EPUB card book. Each EPUB正文 card becomes one Markdown file. The output uses the four-table HyperCard format:
- Luhmann/code + card title
- Card content
- Index-card hyperlinks
- Previous/home/next navigation
Use this skill for EPUBs generated from project notes, Luhmann/Zettelkasten chunks, chapter cards, keyword index cards, or book-check editions that need to become clickable Obsidian Markdown.
Quick Start
Run the generator:
python3 scripts/epub_to_hypercard_obsidian.py INPUT.epub --out OUTPUT_DIR --zip
Recommended portable mode:
python3 scripts/epub_to_hypercard_obsidian.py INPUT.epub --out 3.4-centaur-hypercard-obsidian-portable --zip --portable
The script writes:
index.md: stack home and chapter directorycard-*.md: one正文 card per EPUB article/chapterkeyword-index.md: keyword directorykey-*.md: one keyword index card per keywordOUTPUT_DIR.zip: shareable zip, when--zipis set
Workflow
Inspect the EPUB before converting.
- Confirm it has
META-INF/container.xml,OEBPS/content.opf, XHTML text files, and a spine. - Treat
Text/toc.xhtmlor the first non-article spine item as the directory card. - Treat
Text/index.xhtmlor the XHTML with.index-cardsections as the keyword index card. - Treat XHTML files with
<article>as正文 HyperCards.
- Confirm it has
Generate Markdown card files.
- Use
p.codetext for the card code, such as3.4.1|113字. - Use
h1as the visible card title. - Put body paragraphs into table 2 as one cell, separated with
<br><br>. - Link keyword occurrences to
key-*.md. - Keep Markdown table links as
[label](file.md)to avoid Obsidian heading-anchor drift.
- Use
Generate keyword cards.
- Parse
index.xhtmlsections intoK001, keyword, weight, and target cards. - Make one
key-*.mdper keyword. - Add previous/home/next navigation across keyword cards.
- Parse
Verify all links.
- Every
[label](target.md)must resolve to a file in the output folder. - Do not rely on
[[#heading]]same-file anchors for this workflow. - Prefer
--portablefor sharing with AI tools, GitHub, macOS Finder, Windows, or zip upload workflows.
- Every
Deliver the folder and zip.
- Give the user the output folder path and zip path.
- Report card count, keyword count, and link verification result.
Filename Modes
| Mode | Shape | Use |
|---|---|---|
--portable |
card-3-4-1.md, key-k001.md |
Default recommendation for zip/GitHub/AI upload |
no --portable |
3.4.1-標題.md, K001-關鍵字.md |
More human-readable inside Obsidian, less portable across zip tools |
Four-Table Card Contract
| 魯曼編號 | 卡片標題 |
|---|---|
| `{{code}}` | **{{title}}** |
| 內容 |
|---|
| {{content_with_links}} |
| 索引 | | | |
|---|---|---|---|
| {{keyword_link_1}} | {{keyword_link_2}} | {{keyword_link_3}} | {{keyword_link_4}} |
| ← 上一張 | Card {{n}} / {{total}} | 下一張 → |
|---|---|---|
| {{previous_card}} | [Home](index.md) | {{next_card}} |
Link Rules
- Use relative Markdown file links:
[TARS](key-k001.md). - Do not use Obsidian alias wikilinks inside tables, because
[[target|alias]]contains|and can break table columns. - Do not use same-file heading anchors for card navigation when the user wants a folder or zip.
- Escape Markdown table pipes in extracted text as
\|.
Validation Output
Before finishing, run or report the script validation:
cards: ...
keywords: ...
missing_links: 0
zip: ...
If missing_links is not zero, fix the generated links or parser before delivery.