Skip to main content
skill CX Codex

obsidian2epub — Claude Code skill: what it does, how to install

obsidian2epub converts Obsidian markdown vaults into EPUB ebooks while preserving wikilinks, attachments, and Mermaid diagrams.

MIT 1 installs updated 2026-04-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Unintendedsideeffects/Skills-And-Agents --skill obsidian2epub -a claude-code
Open on GitHub

What obsidian2epub does

The skill instructs the agent to run scripts/convert.sh on an Obsidian directory to build an EPUB file. It converts [[note]] wikilinks into internal ebook anchors, bundles media attachments, and formats the output with Flexoki light or dark themes. Chapters order automatically via the HITS algorithm or follow a designated MOC file supplied with --moc.

Mermaid diagrams require @mermaid-js/mermaid-cli installed globally to render as SVG. Vault contents can be filtered using --include or --exclude regular expressions, and an interactive terminal interface is available via --tui.

What it helps with

  • convert an Obsidian vault into a formatted EPUB ebook
  • render Mermaid markdown diagrams into SVG images
  • structure ebook chapters using an MOC index or the HITS algorithm
  • exclude draft folders from compilation via regex

Example prompts for the agent

  • Convert vault ~/Obsidian/Vault into book.epub using dark theme
  • Export ~/Notes to output.epub and order chapters via Index.md
  • Build an EPUB from ~/Vault excluding files matching ^Drafts/

How to install obsidian2epub

1Skills CLI (Vercel)

npx skills add Unintendedsideeffects/Skills-And-Agents --skill obsidian2epub -a claude-code

2Manually: put the files in place

~/.claude/skills/obsidian2epub/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/obsidian2epub/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about obsidian2epub

How to install obsidian2epub in Claude Code?

Run npx skills add Unintendedsideeffects/Skills-And-Agents --skill obsidian2epub -a claude-code. The skill config will be placed at ~/.claude/skills/obsidian2epub/SKILL.md.

What does obsidian2epub do?

It converts local Obsidian vaults into EPUB ebooks, turning wikilinks into working hyperlinks and embedding attachments.

What is required to render Mermaid diagrams?

You must install the Mermaid CLI tool globally via npm install -g @mermaid-js/mermaid-cli.

Source text

SKILL.md · MIT
---
name: obsidian2epub
description: Convert Obsidian vaults to EPUB ebooks. Use when the user wants to create an ebook from Obsidian notes, export a vault as EPUB, or convert markdown notes to an ebook format.
---

# Obsidian2Epub

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

## Quick Start

```bash
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

```bash
# 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

| Option | Description |
|--------|-------------|
| `-o, --output` | Output EPUB path (required) |
| `--title` | Book title (default: vault name) |
| `--author` | Author name |
| `--moc` | MOC file for chapter ordering |
| `-d, --dark` | Dark Flexoki theme |
| `--include` | Regex to include files |
| `--exclude` | Regex to exclude files |
| `--tui` | Launch interactive TUI |

## 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:
```bash
scripts/convert.sh ~/Obsidian/MyVault -o mybook.epub --title "My Knowledge Base"
```

Include only specific folders:
```bash
scripts/convert.sh ~/Obsidian/MyVault -o book.epub --include "^Projects/"
```

Exclude drafts:
```bash
scripts/convert.sh ~/Obsidian/MyVault -o book.epub --exclude "^Drafts/"
```

## Configuration

Set `OBSIDIAN2EPUB_DIR` environment variable to override the default installation path:

```bash
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

© Unintendedsideeffects · MIT · Unintendedsideeffects/Skills-And-Agents

Similar skills

All skills for Notes, tasks and projects →

Project sponsors

Companies that keep this analytics open