EPUB to Markdown for Obsidian and Notion

Your ebook library is a personal knowledge base waiting to be unlocked. EPUB files contain structured text, chapter hierarchies, and metadata -- but they are trapped inside a format that most note-taking tools cannot ingest. Converting to Markdown sets that content free.

Why Convert Ebooks to Markdown

Searchability. Obsidian, Notion, and similar tools offer full-text search across your vault. But they cannot search inside EPUB files. Convert an ebook to Markdown and every sentence becomes findable.

Linking and backlinks. The power of tools like Obsidian lies in connecting ideas across documents. If a book chapter mentions a concept you have notes on, you want to create a backlink. That requires the content to be in Markdown.

Annotations and highlights. Instead of being locked into a Kindle or Apple Books highlight system, you can annotate directly in your Markdown file -- adding your own notes, tags, and connections inline.

AI-ready. Need to ask an LLM to summarize a chapter, compare arguments across books, or extract key quotes? Markdown is the ideal input format for any model.

What EPUB Contains

An EPUB file is actually a ZIP archive containing:

• XHTML files for each chapter or section
• CSS for styling (fonts, colors, layout)
• Metadata (title, author, publisher, ISBN, language)
• Table of contents (NCX or navigation document)
• Images referenced from the XHTML content

mdstill strips away the CSS and presentational markup, keeping the semantic content: headings, paragraphs, lists, tables, blockquotes, and emphasis. The result is clean Markdown that preserves the book's structure without its visual formatting.

Chapter Structure Preservation

A well-structured EPUB converts to well-structured Markdown. Here is what typical output looks like:

# The Design of Everyday Things

**Author:** Don Norman
**Publisher:** Basic Books

---

## Chapter 1: The Psychopathology of Everyday Things

### The Complexity of Modern Devices

It is not your fault. If you have trouble with
everyday things, it is not due to a lack of
competence on your part...

### The Design Challenge

Design is really about communication. The designer
must communicate with the user through the design
of the product...

## Chapter 2: The Psychology of Everyday Actions

### How People Do Things

People tend to find causes for events, often
attributing them to deliberate actions...

Each EPUB chapter becomes a top-level heading (##), with sub-sections mapping to ### and below. The book title becomes the # heading. This hierarchy translates directly to Obsidian's outline view and Notion's table of contents.

Obsidian Workflow

Here is a practical workflow for building an Obsidian knowledge base from ebooks:

1. Convert. Upload the EPUB to mdstill and download the Markdown file.

2. Split by chapter (optional). For large books, you may want one file per chapter. A simple script handles this:

import re
from pathlib import Path

def split_book(md_path: str, output_dir: str):
    text = Path(md_path).read_text()
    chapters = re.split(r'(?=^## )', text, flags=re.MULTILINE)

    Path(output_dir).mkdir(exist_ok=True)
    for ch in chapters:
        if not ch.strip():
            continue
        title = ch.split('\n')[0].strip('# ').strip()
        safe_name = re.sub(r'[^\w\s-]', '', title)[:60]
        Path(output_dir, f"{safe_name}.md").write_text(ch)

3. Add to vault. Move the files into your Obsidian vault. They are immediately searchable and linkable.

4. Tag and link. Add [[backlinks]] to connect book concepts to your existing notes. Use tags like #book/design or #book/psychology for organization.

5. Create a book index. Maintain a master note that links to all your converted books:

## Reading Library

- [[The Design of Everyday Things]] - Don Norman
- [[Thinking Fast and Slow]] - Daniel Kahneman
- [[The Pragmatic Programmer]] - Hunt & Thomas

Notion Workflow

Notion's Markdown import works well for converted EPUB files:

1. Convert the EPUB to Markdown via mdstill
2. In Notion, use Import > Text & Markdown to bring in the file
3. Notion will parse the headings into its block structure, creating a toggleable table of contents automatically
4. Add the page to a Books database with properties for Author, Genre, Status, and Rating

Notion handles large Markdown files well, so you can import an entire book as a single page. The heading hierarchy becomes Notion's outline, and you can add comments, highlights, and linked databases around the content.

One tip: Notion strips some Markdown features on import (like horizontal rules). If the converted file uses --- for chapter separators, these will become divider blocks in Notion, which actually looks clean.