Obsidian2Epub

Convert Obsidian vaults to well-structured EPUB ebooks with full support for wikilinks, attachments, and Mermaid diagrams.

Quick Start

scripts/convert.sh /path/to/vault -o output.epub

Instructions

1. Get the vault path from the user
2. Determine output EPUB path
3. Ask about optional settings (title, author, theme, filters)
4. Run the conversion using scripts/convert.sh
5. Report any warnings (unresolved links, mermaid failures)

CLI Reference

# Basic conversion
scripts/convert.sh /path/to/vault -o book.epub

# With options
scripts/convert.sh /path/to/vault \
  -o book.epub \
  --title "Book Title" \
  --author "Author Name" \
  --moc "Index.md" \
  -d  # dark Flexoki theme

# Interactive TUI
scripts/convert.sh --tui

Options

Features

• Wikilinks: [[note]] becomes internal EPUB links
• Mermaid: Rendered to SVG (requires npm install -g @mermaid-js/mermaid-cli)
• Smart Ordering: HITS algorithm for chapter order
• Flexoki Themes: Light (default) and dark

Examples

Convert with custom title:

scripts/convert.sh ~/Obsidian/MyVault -o mybook.epub --title "My Knowledge Base"

Include only specific folders:

scripts/convert.sh ~/Obsidian/MyVault -o book.epub --include "^Projects/"

Exclude drafts:

scripts/convert.sh ~/Obsidian/MyVault -o book.epub --exclude "^Drafts/"

Configuration

Set OBSIDIAN2EPUB_DIR environment variable to override the default installation path:

export OBSIDIAN2EPUB_DIR=/path/to/obsidian2epub

Troubleshooting

Mermaid not rendering: Install mermaid-cli: npm install -g @mermaid-js/mermaid-cli

Unresolved wikilinks: Links to notes not in vault are reported as warnings

Missing attachments: Ensure files exist and paths are correct in notes