/epub-hypercard-obsidian

name: epub-hypercard-obsidian
description: 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, backlinks, Luhmann/Zettelkasten numbers, or cross-links into one Markdown file per card with verified relative links, keyword cards, previous/home/next navigation, and GitHub/shareable zip output.

EPUB 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:

1. Luhmann/code + card title 2. Card content 3. Index-card hyperlinks 4. 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 directory
• `card-*.md`: one正文 card per EPUB article/chapter
• `keyword-index.md`: keyword directory
• `key-*.md`: one keyword index card per keyword
• `OUTPUT_DIR.zip`: shareable zip, when `--zip` is set

Workflow

1. Inspect the EPUB before converting.

• Confirm it has `META-INF/container.xml`, `OEBPS/content.opf`, XHTML text files, and a spine.
• Treat `Text/toc.xhtml` or the first non-article spine item as the directory card.
• Treat `Text/index.xhtml` or the XHTML with `.index-card` sections as the keyword index card.
• Treat XHTML files with `<article>` as正文 HyperCards.

2. Generate Markdown card files.

• Use `p.code` text for the card code, such as `3.4.1｜113字`.
• Use `h1` as 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.

3. Generate keyword cards.

• Parse `index.xhtml` sections into `K001`, keyword, weight, and target cards.
• Make one `key-*.md` per keyword.
• Add previous/home/next navigation across keyword cards.

4. 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 `--portable` for sharing with AI tools, GitHub, macOS Finder, Windows, or zip upload workflows.

5. 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.