⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

markdown-to-epub-converter

smerchek@smerchek⭐ 171 stars· last commit 1yr ago· 2 open issues

Convert markdown documents and chat summaries into formatted EPUB ebook files that can be read on any device or uploaded to Kindle.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 171 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Markdown to EPUB Claude Skill

A Claude agent skill that converts markdown documents and chat summaries into professional EPUB ebook files. Perfect for creating portable, device-agnostic ebooks from research documents, blog posts, articles, or conversation summaries.

Overview

This skill transforms markdown content into EPUB3 format ebooks that work across all major reading platforms:

  • Apple Books
  • Amazon Kindle (via Kindle reading apps)
  • Google Play Books
  • Kobo
  • Any standard EPUB reader

Features

✨ Markdown Processing

  • Automatic chapter detection from H1 headers
  • Automatic section parsing from H2-H6 headers
  • Full markdown formatting support (bold, italic, links, lists, code blocks, etc.)
  • Enhanced code blocks with premium monospace fonts and syntax highlighting support
  • Professional tables with styled headers and alternating row colors

📚 EPUB Generation

  • EPUB3 standard compliance
  • Automatic table of contents with proper navigation
  • Responsive, device-agnostic styling
  • Proper document structure and metadata
  • Beautiful code formatting for technical documents

🎯 Smart Input Handling

  • Accept raw markdown text directly
  • Process markdown files by path
  • Extract metadata from YAML frontmatter
  • Handle edge cases gracefully

Project Structure

markdown-to-epub/
├── SKILL.md                    # Skill definition with YAML frontmatter
├── requirements.txt            # Python dependencies
├── scripts/
│   ├── markdown_processor.py  # Markdown parsing & structure extraction
│   ├── epub_generator.py      # EPUB file creation & formatting
└── resources/
    └── default_styles.css     # (future) Custom EPUB styling
test_epub_skill.py             # Test suite with sample content

Installation

Prerequisites

  • Python 3.8+
  • pip (Python package manager)

Setup

  1. Install dependencies:

    pip install -r markdown-to-epub/requirements.txt
    
  2. Verify installation:

    python test_epub_skill.py
    

    You should see all tests pass:

    • ✓ Markdown processing: PASSED
    • ✓ EPUB generation: PASSED
    • ✓ Edge cases: PASSED

Usage

Basic Python Usage

from markdown_to_epub.scripts.epub_generator import create_epub_from_markdown

markdown_content = """
# My Book

## Chapter 1
Content here...
"""

# Generate EPUB
create_epub_from_markdown(
    markdown_content,
    output_path="my_book.epub",
    title="My Book",
    author="John Doe"
)

With Claude Skills Framework

When registered as a Claude skill, simply ask Claude to convert markdown to EPUB:

"Convert this markdown to an EPUB ebook:
# Research Summary
## Introduction
...content..."

Or provide a file path:

"Convert the markdown file at research_notes.md to an EPUB file"

Markdown Support

ElementExampleSupportStyling
Headers# H1 through ###### H6FullOptimized sizes for e-readers
Bold**bold** or __bold__FullStrong emphasis
Italic*italic* or _italic_FullSubtle emphasis
Links[text](url)FullClickable
Lists- item or 1. itemFullProper indentation
Code Blocks```languageEnhancedMonospace fonts, styled backgrounds, blue accent
Inline Code`code`EnhancedGray background, subtle border
TablesMarkdown tablesEnhancedBlue headers, zebra striping, responsive
Blockquotes> quoteFullBlue left border
Horizontal Rule--- or ***FullSubtle divider
ParagraphsText with blank linesFullJustified text

YAML Frontmatter Support

Add metadata to your markdown using YAML frontmatter:

---
title: My Ebook
author: John Doe
language: en
date: 2025-01-15
---

# Chapter 1
...

Supported fields:

  • title - Book title
  • author - Author name
  • language - Language code (default: en)
  • date - Publication date

Architecture

MarkdownProcessor (markdown_processor.py)

  • Parses markdown into structured chapters and sections
  • Extracts metadata from YAML frontmatter
  • Builds table of contents
  • Converts markdown to HTML
  • Handles edge cases (empty content, special characters, etc.)

EPUBGenerator (epub_generator.py)

  • Creates valid EPUB3 files using ebooklib
  • Manages book metadata and document structure
  • Applies consistent styling via embedded CSS
  • Generates navigation documents (NCX, NAV)
  • Handles proper spine/TOC setup

Dependencies

  • ebooklib (0.18.0) - EPUB file creation and manipulation
  • markdown2 (2.4.12) - Markdown utilities (included for future enhancement)

Testing

Run the comprehensive test suite:

python test_epub_skill.py

Tests include:

  • Markdown parsing with various header structures
  • EPUB file generation and validation
  • Edge cases (empty content, plain text, special characters)
  • Long documents (10+ chapters)
  • Table of contents generation
  • Metadata extraction

Future Enhancements

🎨 Cover Page Generation

  • Auto-generate title pages with styling
  • Custom cover images with MCP integration

📱 Kindle Support

  • .mobi and .azw3 format generation
  • Kindle-specific optimizations
  • Direct Kindle device upload capability

🎨 Advanced Styling

  • Custom CSS per user preferences
  • Custom fonts
  • Advanced typography controls

📚 Multi-Document

  • Merge multiple markdown files
  • Cross-document references
  • Advanced chapter organization

Technical Details

  • EPUB Version: EPUB3 (2023 standard)
  • HTML Standard: XHTML 1.1
  • Character Encoding: UTF-8
  • CSS Support: Responsive, embedded styling
  • Navigation: NCX (compatibility) + NAV (EPUB3 standard)

Troubleshooting

EPUB won't open

  • Verify markdown uses proper syntax
  • Check for balanced brackets in links
  • Ensure chapters have H1 headers

Missing table of contents

  • Add H1 headers to mark chapter boundaries
  • Verify headers are followed by content

Formatting looks different

  • This is normal! EPUB readers apply their own fonts and styling
  • Structure is preserved across all readers

Large file size

  • Compress with external tools if needed
  • Remove large embedded content if applicable

License

This skill follows the same license as the Claude Cookbooks project.

Contributing

Contributions are welcome! Areas for improvement:

  • Additional markdown features (tables, footnotes)
  • Enhanced styling options
  • Performance optimizations
  • Additional format support

Related Resources


Created: 2025-01-16 Version: 1.0.0 Status: Production Ready

// HOW IT'S BUILT

// FILES

6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • markdown-to-epub/SKILL.md6.4 KBe59c8330c724upstream ↗
    ---
    name: markdown-to-epub-converter
    description: Convert markdown documents and chat summaries into formatted EPUB ebook files that can be read on any device or uploaded to Kindle.
    ---
    
    # Markdown to EPUB Converter Skill
    
    This skill transforms markdown documents into professional EPUB ebook files. Perfect for converting research documents, blog posts, articles, or chat conversation summaries into portable, device-agnostic ebook formats.
    
    ## Overview
    
    The skill accepts markdown content in multiple formats and generates a properly formatted EPUB3 file that works across all major ebook readers including:
    - Apple Books
    - Amazon Kindle (via Kindle for Mac/Windows/iOS/Android)
    - Google Play Books
    - Kobo and other EPUB readers
    - Any standard EPUB reader
    
    ## Input Formats
    
    ### Option 1: Raw Markdown Text
    Provide markdown content directly in your message:
    
    ```
    Convert this markdown to EPUB:
    # My Book Title
    ## Chapter 1
    This is chapter one content...
    ```
    
    ### Option 2: File Path
    Provide a path to a markdown file to be converted.
    
    ## How It Works
    
    1. **Markdown Parsing**: Analyzes your markdown and automatically:
       - Treats H1 headers (`#`) as chapter boundaries
       - Treats H2 headers (`##`) as section headings within chapters
       - Preserves formatting (bold, italic, links, lists, code blocks)
    
    2. **Structure Generation**: Creates proper EPUB structure:
       - Automatic table of contents from chapters
       - Navigation document (EPUB3 standard)
       - Metadata (title, language, etc.)
    
    3. **File Creation**: Generates a valid EPUB3 file ready for download and use
    
    ## Usage Examples
    
    ### Example 1: Convert a Blog Post
    "Convert this markdown blog post to EPUB:
    # How to Build a Simple Web Server
    ## Introduction
    ...content..."
    
    ### Example 2: Convert a Research Summary
    "I have research notes in markdown format. Convert them to an EPUB ebook. The content is:
    # Research Project: Machine Learning Basics
    ## Chapter 1: Fundamentals
    ..."
    
    ### Example 3: Convert a Chat Summary
    "Summarize our conversation so far as markdown and convert it to an EPUB for reference"
    
    ## Output
    
    The skill generates a downloadable EPUB file that includes:
    - Professional formatting
    - Automatic table of contents
    - Proper chapter structure
    - Support for markdown formatting elements:
      - Headers (all levels)
      - Bold and italic text
      - Hyperlinks
      - Lists (ordered and unordered)
      - Code blocks and inline code
      - Blockquotes
      - Horizontal rules
    
    ## Markdown Elements Supported
    
    | Element | Markdown | Support | Notes |
    |---------|----------|---------|-------|
    | Headers | `# H1` through `###### H6` | Full | Auto TOC generation |
    | Bold | `**text**` or `__text__` | Full | |
    | Italic | `*text*` or `_text_` | Full | |
    | Links | `[text](url)` | Full | Clickable in ebooks |
    | Lists | `- item` or `1. item` | Full | Nested lists supported |
    | Code blocks | ` ```language ` | **Enhanced** | Syntax highlighting ready, monospace fonts |
    | Inline code | ` `code` ` | **Enhanced** | Styled background, borders |
    | Tables | Markdown tables | **Enhanced** | Styled headers, alternating rows |
    | Blockquotes | `> quote` | Full | Styled with left border |
    | Horizontal rule | `---` or `***` | Full | |
    
    ## Advanced Features
    
    ### Enhanced Code Block Support
    
    Code blocks are beautifully formatted with:
    - **Premium monospace fonts**: SF Mono, Monaco, Fira Code, Consolas, and more
    - **Styled backgrounds**: Subtle gray background with blue accent border
    - **Language detection**: Specify language after ` ``` ` for future syntax highlighting
    - **Proper escaping**: HTML characters are safely escaped
    - **Overflow handling**: Horizontal scrolling for long lines
    
    Example:
    ```python
    def fibonacci(n):
        if n <= 1:
            return n
        return fibonacci(n-1) + fibonacci(n-2)
    ```
    
    ### Enhanced Table Support
    
    Tables are rendered with professional styling:
    - **Styled headers**: Blue background with white text
    - **Alternating rows**: Zebra striping for readability
    - **Cell padding**: Comfortable spacing for easy reading
    - **Inline formatting**: Code, bold, italic, and links work in cells
    - **Responsive**: Tables adapt to different screen sizes
    
    Example:
    | Feature | Status | Notes |
    |---------|--------|-------|
    | Headers | ✓ | Full support |
    | Code | ✓ | Enhanced styling |
    | Tables | ✓ | Professional layout |
    
    ### Custom Title and Metadata
    You can specify EPUB metadata:
    - Book title (defaults to first H1 header)
    - Author name
    - Language
    - Publication date
    
    ### Chapter Organization
    Chapters are automatically detected from:
    - H1 headers (`#`) as primary chapter breaks
    - Logical content sections between H1s
    - Automatic page breaks between chapters
    
    ### Styling
    The generated EPUB uses clean, readable default styling that:
    - Respects the reader's font preferences
    - Works on all screen sizes
    - Maintains proper spacing and hierarchy
    - Includes appropriate margins and padding
    
    ## Technical Details
    
    - **Format**: EPUB3 (compatible with all modern readers)
    - **Encoding**: UTF-8
    - **HTML Version**: XHTML 1.1
    - **CSS Support**: Responsive styling
    
    ## Downloading Your EPUB
    
    After generation, the file will be available for download. You can then:
    1. Download the EPUB to your computer
    2. Open it with your preferred ebook reader
    3. Transfer to your Kindle, iPad, or other device
    4. Upload directly to Kindle via email or cloud
    
    ## Tips for Best Results
    
    1. **Use Proper Markdown Structure**: The skill works best when markdown follows standard conventions (H1 for titles, H2 for sections)
    
    2. **Clear Chapter Breaks**: Use H1 headers to clearly mark chapter divisions
    
    3. **Descriptive Headers**: Headers become the table of contents, so make them clear and descriptive
    
    4. **Content Organization**: Place content logically between headers
    
    5. **Supported Formatting**: Stick to basic markdown formatting for best compatibility across all readers
    
    ## Troubleshooting
    
    **EPUB doesn't open**: Ensure your markdown is properly formatted. Check for matching brackets in links and proper syntax.
    
    **Table of contents is empty**: Make sure your markdown includes H1 headers to define chapters.
    
    **Formatting looks different**: EPUB readers apply their own fonts and styling. This is normal and expected behavior.
    
    ## Scripts
    
    - `epub_generator.py` - Core EPUB file creation and formatting
    - `markdown_processor.py` - Markdown parsing and structure extraction
    
    ## Future Enhancements
    
    - Auto-generated cover pages with custom images
    - Kindle-specific optimizations (.mobi format)
    - Custom CSS styling per user preferences
    - Multi-document merging
    - Image embedding and optimization
    - Advanced metadata support
    
  • markdown-to-epub/scripts/epub_generator.py13 KBbe2b736b0961upstream ↗
    """
    EPUB file generation module.
    
    This module handles creating proper EPUB3 files from parsed markdown structure
    using the ebooklib library.
    """
    
    import uuid
    from pathlib import Path
    from typing import List, Optional, Dict
    from datetime import datetime
    
    from ebooklib import epub
    
    from markdown_processor import (
        Chapter, Section, EbookMetadata, MarkdownProcessor
    )
    
    
    class EPUBGenerator:
        """Generate EPUB3 files from markdown chapters and sections."""
    
        # Default CSS for EPUB styling
        DEFAULT_CSS = """
        body {
            font-family: Georgia, serif;
            font-size: 75%;
            line-height: 1.5;
            margin: 0;
            padding: 1em;
        }
    
        h1 {
            font-size: 1.3em;
            font-weight: bold;
            margin: 1.5em 0 0.75em 0;
            color: #1a1a1a;
            page-break-before: always;
        }
    
        h2 {
            font-size: 1.15em;
            font-weight: bold;
            margin: 1.25em 0 0.5em 0;
            color: #2c3e50;
        }
    
        h3 {
            font-size: 1.05em;
            font-weight: bold;
            margin: 1em 0 0.5em 0;
            color: #34495e;
        }
    
        h4, h5, h6 {
            font-size: 0.95em;
            font-weight: bold;
            margin: 0.75em 0 0.5em 0;
        }
    
        p {
            margin: 0.75em 0;
            text-align: justify;
            font-size: 1em;
        }
    
        a {
            color: #0066cc;
            text-decoration: none;
        }
    
        a:visited {
            color: #663399;
        }
    
        strong {
            font-weight: bold;
        }
    
        em {
            font-style: italic;
        }
    
        code, pre {
            font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code', 'Fira Mono', 'Roboto Mono', 'Consolas', 'Courier New', monospace;
            font-size: 0.72em;
        }
    
        code {
            background-color: #f5f5f5;
            padding: 0.15em 0.4em;
            border-radius: 3px;
            border: 1px solid #e0e0e0;
        }
    
        pre {
            background-color: #f8f8f8;
            border: 1px solid #e0e0e0;
            border-left: 3px solid #0066cc;
            padding: 0.8em;
            overflow-x: auto;
            margin: 1em 0;
            border-radius: 4px;
            line-height: 1.3;
            tab-size: 2;
            -moz-tab-size: 2;
        }
    
        pre code {
            padding: 0;
            background-color: transparent;
            border: none;
            font-size: 1em;
            line-height: 1.3;
        }
    
        /* Line numbers in code blocks */
        .line-number {
            display: inline-block;
            width: 2.2em;
            text-align: right;
            padding-right: 0.3em;
            color: #999;
            user-select: none;
            -webkit-user-select: none;
            -moz-user-select: none;
            border-right: 1px solid #ddd;
            margin-right: 0.4em;
        }
    
        .line-content {
            display: inline;
        }
    
        /* Syntax highlighting (Pygments-based) */
        .syn-keyword {
            color: #0066cc;
            font-weight: 600;
        }
    
        .syn-string {
            color: #22863a;
        }
    
        .syn-comment {
            color: #6a737d;
            font-style: italic;
        }
    
        .syn-number {
            color: #005cc5;
        }
    
        .syn-function {
            color: #6f42c1;
        }
    
        .syn-class {
            color: #d73a49;
            font-weight: 600;
        }
    
        blockquote {
            border-left: 4px solid #0066cc;
            margin: 1em 0;
            padding-left: 1em;
            color: #555;
            font-style: italic;
        }
    
        ul, ol {
            margin: 0.75em 0;
            padding-left: 2em;
        }
    
        li {
            margin: 0.5em 0;
        }
    
        table {
            border-collapse: collapse;
            width: 100%;
            margin: 1.5em 0;
            font-size: 0.88em;
            border: 1px solid #ddd;
        }
    
        thead {
            background-color: #0066cc;
            color: white;
        }
    
        th {
            padding: 0.75em 1em;
            text-align: left;
            font-weight: bold;
            border: 1px solid #0052a3;
        }
    
        td {
            padding: 0.65em 1em;
            border: 1px solid #ddd;
            text-align: left;
        }
    
        tbody tr:nth-child(even) {
            background-color: #f8f9fa;
        }
    
        tbody tr:hover {
            background-color: #f0f0f0;
        }
    
        /* Code in table cells */
        td code, th code {
            font-size: 0.85em;
        }
    
        hr {
            border: none;
            border-top: 2px solid #ddd;
            margin: 2em 0;
        }
    
        .toc-entry {
            margin: 0.5em 0;
        }
    
        .toc-entry-h2 {
            margin-left: 1.5em;
        }
    
        .toc-entry-h3 {
            margin-left: 3em;
        }
        """
    
        def __init__(self, metadata: EbookMetadata = None):
            """
            Initialize EPUB generator.
    
            Args:
                metadata: EbookMetadata object with title, author, etc.
            """
            self.metadata = metadata or EbookMetadata()
            self.book = None
            self.chapters = []
            self.toc_items = []
    
        def generate(self, chapters: List[Chapter], output_path: str) -> bool:
            """
            Generate EPUB file from chapters.
    
            Args:
                chapters: List of Chapter objects from markdown parser
                output_path: Path where EPUB file should be saved
    
            Returns:
                True if successful, False otherwise
            """
            try:
                self.chapters = chapters
                self._create_book()
                self._add_chapters()
                self._add_style()
                self._add_toc()
                self._write_epub(output_path)
                return True
            except Exception as e:
                print(f"Error generating EPUB: {e}")
                raise
    
        def _create_book(self) -> None:
            """Create and configure EPUB book object."""
            self.book = epub.EpubBook()
    
            # Set metadata
            self.book.set_identifier(self.metadata.identifier or str(uuid.uuid4()))
            self.book.set_title(self.metadata.title or "Untitled Book")
            self.book.set_language(self.metadata.language)
    
            if self.metadata.author:
                self.book.add_author(self.metadata.author)
    
        def _add_chapters(self) -> None:
            """Add chapters to EPUB."""
            all_items = []
    
            for chapter_idx, chapter in enumerate(self.chapters):
                # Create chapter HTML file
                chapter_html = self._render_chapter(chapter)
                chapter_file = epub.EpubHtml(
                    title=chapter.title,
                    file_name=f'chap_{chapter_idx + 1:03d}.xhtml',
                    lang=self.metadata.language
                )
                # ebooklib's set_content expects the body content, not full XHTML
                # Extract just the body content
                body_match = chapter_html.find('<body>')
                if body_match != -1:
                    body_start = body_match + 6
                    body_end = chapter_html.find('</body>')
                    body_content = chapter_html[body_start:body_end]
                else:
                    body_content = chapter_html
    
                chapter_file.set_content(body_content)
    
                self.book.add_item(chapter_file)
                all_items.append(chapter_file)
    
                # Add chapter to TOC
                section_items = []
                for section in chapter.sections:
                    section_items.append(section)
    
                self.toc_items.append((chapter, section_items))
    
        def _render_chapter(self, chapter: Chapter) -> str:
            """
            Render chapter to XHTML.
    
            Args:
                chapter: Chapter object
    
            Returns:
                XHTML string
            """
            html_parts = []
    
            # Chapter title
            if chapter.title:
                html_parts.append(f'<h1 id="{chapter.anchor}">{self._escape_html(chapter.title)}</h1>')
    
            # Chapter content
            if chapter.content:
                html_parts.append(self._render_content(chapter.content))
    
            # Sections
            for section in chapter.sections:
                html_parts.append(f'<h{section.level} id="{section.anchor}">{self._escape_html(section.title)}</h{section.level}>')
                if section.content:
                    html_parts.append(self._render_content(section.content))
    
            # Ensure we have some content
            content = '\n'.join(html_parts)
            if not content.strip():
                # Add empty paragraph if no content
                content = '<p></p>'
    
            # Wrap in proper XHTML document
            xhtml = f"""<?xml version='1.0' encoding='utf-8'?>
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{self.metadata.language}">
    <head>
        <title>{self._escape_html(chapter.title)}</title>
    </head>
    <body>
    {content}
    </body>
    </html>"""
    
            return xhtml
    
        def _render_content(self, content: str) -> str:
            """
            Render markdown content to HTML.
    
            Args:
                content: Markdown content
    
            Returns:
                HTML string
            """
            if not content:
                return ""
    
            # Use markdown processor to convert to HTML
            html = MarkdownProcessor.markdown_to_html(content)
            return html
    
        def _add_style(self) -> None:
            """Add CSS styling to EPUB."""
            if not self.book:
                return
    
            style = epub.EpubItem()
            style.file_name = 'style/main.css'
            style.media_type = 'text/css'
            style.set_content(self.DEFAULT_CSS)
    
            self.book.add_item(style)
    
            # Add CSS to all chapters
            for item in self.book.items:
                if isinstance(item, epub.EpubHtml):
                    item.add_link(
                        rel='stylesheet',
                        href='style/main.css',
                        type='text/css'
                    )
    
        def _add_toc(self) -> None:
            """Add table of contents to EPUB."""
            if not self.book or not self.toc_items:
                return
    
            toc_items = []
    
            for chapter, sections in self.toc_items:
                # Find chapter item in book
                chapter_link = None
                for item in self.book.items:
                    if isinstance(item, epub.EpubHtml) and item.title == chapter.title:
                        chapter_link = item
                        break
    
                if chapter_link:
                    if sections:
                        # Chapter with sections - create nested structure
                        section_links = []
                        for section in sections:
                            # Add anchor to section headers in rendered HTML
                            section_links.append(
                                epub.Link(
                                    f"{chapter_link.file_name}#{section.anchor}",
                                    section.title,
                                    f"sec_{section.anchor}"
                                )
                            )
                        # Add chapter with nested sections as tuple
                        toc_items.append((chapter_link, section_links))
                    else:
                        # Chapter without sections
                        toc_items.append(chapter_link)
    
            if toc_items:
                self.book.toc = tuple(toc_items)
    
        def _write_epub(self, output_path: str) -> None:
            """
            Write EPUB file to disk.
    
            Args:
                output_path: Path where EPUB should be saved
            """
            if not self.book:
                raise ValueError("Book not initialized")
    
            # Ensure output directory exists
            Path(output_path).parent.mkdir(parents=True, exist_ok=True)
    
            # Add navigation items (must be added before setting spine)
            ncx = epub.EpubNcx()
            nav = epub.EpubNav()
    
            self.book.add_item(ncx)
            self.book.add_item(nav)
    
            # Define spine - only include HTML items, nav is implicit
            html_items = [item for item in self.book.items if isinstance(item, epub.EpubHtml)]
            self.book.spine = html_items
    
            # Write EPUB
            epub.write_epub(output_path, self.book, {})
    
        @staticmethod
        def _escape_html(text: str) -> str:
            """Escape HTML special characters."""
            if not text:
                return ""
            return (text
                    .replace('&', '&amp;')
                    .replace('<', '&lt;')
                    .replace('>', '&gt;')
                    .replace('"', '&quot;')
                    .replace("'", '&#39;'))
    
    
    def create_epub_from_markdown(markdown_content: str, output_path: str,
                                  title: Optional[str] = None,
                                  author: Optional[str] = None) -> bool:
        """
        Convenience function to create EPUB from markdown content.
    
        Args:
            markdown_content: Raw markdown text
            output_path: Path where EPUB should be saved
            title: Book title (optional, will use first H1 if not provided)
            author: Author name (optional)
    
        Returns:
            True if successful, False otherwise
        """
        # Parse markdown
        processor = MarkdownProcessor()
        result = processor.process(markdown_content)
    
        # Create metadata
        metadata = result['metadata']
        if title:
            metadata.title = title
        if author:
            metadata.author = author
    
        # Generate EPUB
        generator = EPUBGenerator(metadata)
        return generator.generate(result['chapters'], output_path)
    
  • markdown-to-epub/scripts/markdown_processor.py24 KBaa66b3c2d293upstream ↗
    """
    Markdown processing module for converting markdown to EPUB-compatible structure.
    
    This module handles:
    - Parsing markdown into chapters and sections
    - Converting markdown to HTML
    - Extracting metadata and structure
    - Building table of contents
    """
    
    import re
    from typing import List, Dict, Tuple, Optional
    from dataclasses import dataclass
    from enum import Enum
    
    try:
        from pygments import highlight
        from pygments.lexers import get_lexer_by_name, guess_lexer, TextLexer
        from pygments.formatters import HtmlFormatter
        from pygments.util import ClassNotFound
        PYGMENTS_AVAILABLE = True
    except ImportError:
        PYGMENTS_AVAILABLE = False
    
    
    class HeaderLevel(Enum):
        """Header hierarchy levels."""
        H1 = 1
        H2 = 2
        H3 = 3
        H4 = 4
        H5 = 5
        H6 = 6
    
    
    @dataclass
    class Header:
        """Represents a markdown header."""
        level: HeaderLevel
        text: str
        anchor: Optional[str] = None
    
        def __post_init__(self):
            if not self.anchor:
                # Generate anchor from text
                self.anchor = re.sub(r'[^\w\s-]', '', self.text.lower())
                self.anchor = re.sub(r'[-\s]+', '-', self.anchor).strip('-')
    
    
    @dataclass
    class Chapter:
        """Represents a chapter (H1 section)."""
        title: str
        content: str
        sections: List['Section']
        anchor: Optional[str] = None
    
        def __post_init__(self):
            if not self.anchor:
                self.anchor = re.sub(r'[^\w\s-]', '', self.title.lower())
                self.anchor = re.sub(r'[-\s]+', '-', self.anchor).strip('-')
    
    
    @dataclass
    class Section:
        """Represents a section (H2-H6)."""
        title: str
        level: int
        content: str
        anchor: Optional[str] = None
    
        def __post_init__(self):
            if not self.anchor:
                self.anchor = re.sub(r'[^\w\s-]', '', self.title.lower())
                self.anchor = re.sub(r'[-\s]+', '-', self.anchor).strip('-')
    
    
    @dataclass
    class EbookMetadata:
        """Metadata for the ebook."""
        title: Optional[str] = None
        author: Optional[str] = "Unknown Author"
        language: str = "en"
        date: Optional[str] = None
        identifier: Optional[str] = None
    
    
    class MarkdownProcessor:
        """Process markdown content into EPUB-compatible structure."""
    
        def __init__(self):
            """Initialize the markdown processor."""
            self.chapters: List[Chapter] = []
            self.metadata = EbookMetadata()
            self.front_matter: Dict[str, str] = {}
    
        def process(self, markdown_content: str) -> Dict:
            """
            Process markdown content into structured format.
    
            Args:
                markdown_content: Raw markdown text
    
            Returns:
                Dictionary containing chapters, metadata, and TOC
            """
            # Extract front matter if present
            content = self._extract_frontmatter(markdown_content)
    
            # Extract metadata from headers
            self._extract_metadata(content)
    
            # Parse content into chapters
            self.chapters = self._parse_chapters(content)
    
            # Build table of contents
            toc = self._build_toc()
    
            return {
                'chapters': self.chapters,
                'metadata': self.metadata,
                'toc': toc,
                'front_matter': self.front_matter
            }
    
        def _extract_frontmatter(self, content: str) -> str:
            """
            Extract YAML front matter if present.
    
            Args:
                content: Raw markdown content
    
            Returns:
                Markdown content without front matter
            """
            if not content.startswith('---'):
                return content
    
            # Find closing ---
            try:
                end_idx = content.index('---', 3)
                fm_text = content[3:end_idx].strip()
    
                # Parse simple key: value pairs
                for line in fm_text.split('\n'):
                    if ':' in line:
                        key, value = line.split(':', 1)
                        self.front_matter[key.strip().lower()] = value.strip()
    
                # Update metadata from front matter
                if 'title' in self.front_matter:
                    self.metadata.title = self.front_matter['title']
                if 'author' in self.front_matter:
                    self.metadata.author = self.front_matter['author']
                if 'date' in self.front_matter:
                    self.metadata.date = self.front_matter['date']
                if 'language' in self.front_matter:
                    self.metadata.language = self.front_matter['language']
    
                return content[end_idx + 3:].lstrip()
            except ValueError:
                return content
    
        def _extract_metadata(self, content: str) -> None:
            """
            Extract metadata from document headers.
    
            Args:
                content: Markdown content
            """
            # If no title from front matter, use first H1
            if not self.metadata.title:
                h1_match = re.search(r'^# (.+)$', content, re.MULTILINE)
                if h1_match:
                    self.metadata.title = h1_match.group(1).strip()
    
        def _parse_chapters(self, content: str) -> List[Chapter]:
            """
            Parse markdown into chapters.
    
            Chapters are delimited by H1 headers. Content between H1s
            becomes a chapter with potential subsections (H2-H6).
    
            Args:
                content: Markdown content
    
            Returns:
                List of Chapter objects
            """
            # First, remove code blocks to avoid matching headers inside them
            # We'll use a placeholder to mark where code blocks were
            code_blocks = []
            code_block_pattern = r'```[^\n]*\n.*?```'
    
            def save_code_block(match):
                code_blocks.append(match.group(0))
                return f'\n__CODE_BLOCK_{len(code_blocks)-1}__\n'
    
            content_no_code = re.sub(code_block_pattern, save_code_block, content, flags=re.DOTALL)
    
            # Split by H1 headers (now safe from code blocks)
            h1_pattern = r'^# (.+)$'
            chapters = []
    
            # Find all H1 headers and their positions in content WITHOUT code blocks
            h1_matches = list(re.finditer(h1_pattern, content_no_code, re.MULTILINE))
    
            if not h1_matches:
                # No chapters, treat entire content as single chapter
                if content.strip():
                    sections = self._parse_sections(content, 2)  # Start from H2
                    chapters.append(Chapter(
                        title="Untitled",
                        content="",
                        sections=sections
                    ))
                return chapters
    
            # Process each chapter
            # We need to map positions from content_no_code back to original content
            for i, match in enumerate(h1_matches):
                title = match.group(1).strip()
                start_no_code = match.end()
    
                # Find next H1 or end of content
                if i + 1 < len(h1_matches):
                    end_no_code = h1_matches[i + 1].start()
                else:
                    end_no_code = len(content_no_code)
    
                # Get the chapter content from content_no_code
                chapter_content_no_code = content_no_code[start_no_code:end_no_code]
    
                # Restore code blocks
                def restore_code_block(match):
                    idx = int(match.group(1))
                    return code_blocks[idx]
    
                chapter_content = re.sub(r'__CODE_BLOCK_(\d+)__', restore_code_block, chapter_content_no_code).rstrip()
    
                # Parse sections within this chapter
                sections = self._parse_sections(chapter_content, 2)
    
                # Extract direct content (before first H2)
                direct_content = ""
                if sections:
                    first_h2_pos = chapter_content.find('\n##')
                    if first_h2_pos == -1:
                        direct_content = chapter_content
                    else:
                        direct_content = chapter_content[:first_h2_pos].strip()
                else:
                    direct_content = chapter_content
    
                chapters.append(Chapter(
                    title=title,
                    content=direct_content,
                    sections=sections
                ))
    
            return chapters
    
        def _parse_sections(self, content: str, min_level: int = 2) -> List[Section]:
            """
            Parse sections from content (H2 and below).
    
            Args:
                content: Markdown content
                min_level: Minimum header level to parse (2-6)
    
            Returns:
                List of Section objects
            """
            sections = []
    
            # Build pattern for headers from min_level to 6
            header_pattern = r'^(#{' + str(min_level) + r',6}) (.+)$'
            matches = list(re.finditer(header_pattern, content, re.MULTILINE))
    
            if not matches:
                return sections
    
            for i, match in enumerate(matches):
                hashes = match.group(1)
                level = len(hashes)
                title = match.group(2).strip()
                start = match.end()
    
                # Find next header or end
                if i + 1 < len(matches):
                    end = matches[i + 1].start()
                else:
                    end = len(content)
    
                section_content = content[start:end].rstrip()
    
                sections.append(Section(
                    title=title,
                    level=level,
                    content=section_content
                ))
    
            return sections
    
        def _build_toc(self) -> List[Dict]:
            """
            Build table of contents from chapters and sections.
    
            Returns:
                List of TOC entries with links and hierarchy
            """
            toc = []
    
            for chapter in self.chapters:
                chapter_entry = {
                    'title': chapter.title,
                    'anchor': chapter.anchor,
                    'level': 1,
                    'subsections': []
                }
    
                for section in chapter.sections:
                    section_entry = {
                        'title': section.title,
                        'anchor': section.anchor,
                        'level': section.level
                    }
                    chapter_entry['subsections'].append(section_entry)
    
                toc.append(chapter_entry)
    
            return toc
    
        @staticmethod
        def markdown_to_html(markdown_text: str) -> str:
            """
            Convert markdown to HTML.
    
            This is a simplified converter for common markdown elements.
    
            Args:
                markdown_text: Markdown text
    
            Returns:
                HTML string
            """
            if not markdown_text or not markdown_text.strip():
                return "<p></p>"
    
            lines = markdown_text.split('\n')
            html_parts = []
            in_code_block = False
            code_block_content = []
            code_block_language = None
            in_table = False
            table_lines = []
            current_paragraph = []
    
            for line in lines:
                # Handle code blocks
                if line.strip().startswith('```'):
                    if in_code_block:
                        # End code block
                        code_html = '\n'.join(code_block_content)
                        # Add line numbers and syntax highlighting
                        code_html = MarkdownProcessor._add_line_numbers_and_highlighting(
                            code_html, code_block_language
                        )
                        html_parts.append(code_html)
                        code_block_content = []
                        code_block_language = None
                        in_code_block = False
                    else:
                        # Start code block
                        if current_paragraph:
                            paragraph_text = ' '.join(current_paragraph).strip()
                            if paragraph_text:
                                html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                            current_paragraph = []
                        # Extract language if specified
                        lang = line.strip()[3:].strip()
                        code_block_language = lang if lang else None
                        in_code_block = True
                    continue
    
                if in_code_block:
                    code_block_content.append(line)
                    continue
    
                # Handle tables
                if '|' in line and line.strip().startswith('|') or (line.count('|') >= 2):
                    if not in_table:
                        # Start table
                        if current_paragraph:
                            paragraph_text = ' '.join(current_paragraph).strip()
                            if paragraph_text:
                                html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                            current_paragraph = []
                        in_table = True
                    table_lines.append(line)
                    continue
                elif in_table:
                    # End of table
                    table_html = MarkdownProcessor._parse_table(table_lines)
                    if table_html:
                        html_parts.append(table_html)
                    table_lines = []
                    in_table = False
                    # Fall through to process current line
    
                # Handle blockquotes
                if line.strip().startswith('>'):
                    if current_paragraph:
                        paragraph_text = ' '.join(current_paragraph).strip()
                        if paragraph_text:
                            html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                        current_paragraph = []
                    quote_text = line.lstrip('> ').strip()
                    html_parts.append(f'<blockquote>{MarkdownProcessor._render_inline(quote_text)}</blockquote>')
                    continue
    
                # Handle headers
                if line.startswith('#'):
                    if current_paragraph:
                        paragraph_text = ' '.join(current_paragraph).strip()
                        if paragraph_text:
                            html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                        current_paragraph = []
    
                    level = len(line) - len(line.lstrip('#'))
                    header_text = line.lstrip('# ').strip()
                    if level <= 6:
                        html_parts.append(f'<h{level}>{MarkdownProcessor._render_inline(header_text)}</h{level}>')
                    continue
    
                # Handle lists
                if line.strip().startswith(('- ', '* ')) or re.match(r'^\d+\.\s', line.strip()):
                    if current_paragraph:
                        paragraph_text = ' '.join(current_paragraph).strip()
                        if paragraph_text:
                            html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                        current_paragraph = []
    
                    list_item = re.sub(r'^[-*\d.]\s+', '', line.strip())
                    html_parts.append(f'<li>{MarkdownProcessor._render_inline(list_item)}</li>')
                    continue
    
                # Handle horizontal rules
                if line.strip() in ('---', '***', '___'):
                    if current_paragraph:
                        paragraph_text = ' '.join(current_paragraph).strip()
                        if paragraph_text:
                            html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                        current_paragraph = []
                    html_parts.append('<hr/>')
                    continue
    
                # Handle empty lines (paragraph break)
                if not line.strip():
                    if current_paragraph:
                        paragraph_text = ' '.join(current_paragraph).strip()
                        if paragraph_text:
                            html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
                        current_paragraph = []
                    continue
    
                # Add to current paragraph
                current_paragraph.append(line.strip())
    
            # Finish any remaining paragraph
            if current_paragraph:
                paragraph_text = ' '.join(current_paragraph).strip()
                if paragraph_text:
                    html_parts.append(f'<p>{MarkdownProcessor._render_inline(paragraph_text)}</p>')
    
            # Finish any remaining table
            if in_table and table_lines:
                table_html = MarkdownProcessor._parse_table(table_lines)
                if table_html:
                    html_parts.append(table_html)
    
            html = '\n'.join(html_parts) if html_parts else '<p></p>'
            return html
    
        @staticmethod
        def _render_inline(text: str) -> str:
            """
            Render inline markdown elements (bold, italic, links, code).
    
            Args:
                text: Text with inline markdown
    
            Returns:
                HTML string
            """
            # Escape HTML special characters first, but be careful with our markers
            text = (text
                    .replace('&', '&amp;')
                    .replace('<', '&lt;')
                    .replace('>', '&gt;'))
    
            # Bold
            text = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', text)
            text = re.sub(r'__(.+?)__', r'<strong>\1</strong>', text)
    
            # Italic
            text = re.sub(r'\*(.+?)\*', r'<em>\1</em>', text)
            text = re.sub(r'_(.+?)_', r'<em>\1</em>', text)
    
            # Inline code
            text = re.sub(r'`(.+?)`', r'<code>\1</code>', text)
    
            # Links
            text = re.sub(r'\[(.+?)\]\((.+?)\)', r'<a href="\2">\1</a>', text)
    
            return text
    
        @staticmethod
        def _parse_table(table_lines: List[str]) -> str:
            """
            Parse markdown table into HTML.
    
            Args:
                table_lines: List of table lines
    
            Returns:
                HTML table string
            """
            if not table_lines or len(table_lines) < 2:
                return ""
    
            # Remove empty lines
            table_lines = [line.strip() for line in table_lines if line.strip()]
    
            if len(table_lines) < 2:
                return ""
    
            # Parse header
            header_line = table_lines[0]
            headers = [cell.strip() for cell in header_line.split('|')]
            headers = [h for h in headers if h]  # Remove empty cells
    
            # Skip separator line (second line with dashes)
            if len(table_lines) < 2:
                return ""
    
            # Check if second line is separator
            separator = table_lines[1]
            if not re.match(r'^[\s|:-]+$', separator):
                # Not a valid table
                return ""
    
            # Parse data rows
            rows = []
            for line in table_lines[2:]:
                cells = [cell.strip() for cell in line.split('|')]
                cells = [c for c in cells if c]  # Remove empty cells from leading/trailing pipes
                if cells:
                    rows.append(cells)
    
            # Build HTML table
            html_parts = ['<table>']
    
            # Header
            html_parts.append('<thead><tr>')
            for header in headers:
                html_parts.append(f'<th>{MarkdownProcessor._render_inline(header)}</th>')
            html_parts.append('</tr></thead>')
    
            # Body
            if rows:
                html_parts.append('<tbody>')
                for row in rows:
                    html_parts.append('<tr>')
                    for i, cell in enumerate(row):
                        if i < len(headers):  # Don't exceed header count
                            html_parts.append(f'<td>{MarkdownProcessor._render_inline(cell)}</td>')
                    # Fill missing cells
                    for i in range(len(row), len(headers)):
                        html_parts.append('<td></td>')
                    html_parts.append('</tr>')
                html_parts.append('</tbody>')
    
            html_parts.append('</table>')
    
            return '\n'.join(html_parts)
    
        @staticmethod
        def escape_html(text: str) -> str:
            """Escape HTML special characters."""
            return (text
                    .replace('&', '&amp;')
                    .replace('<', '&lt;')
                    .replace('>', '&gt;')
                    .replace('"', '&quot;')
                    .replace("'", '&#39;'))
    
        @staticmethod
        def _add_line_numbers_and_highlighting(code: str, language: Optional[str] = None) -> str:
            """
            Add line numbers and syntax highlighting to code block using Pygments.
    
            Args:
                code: Raw code string
                language: Programming language identifier
    
            Returns:
                HTML string with line numbers and syntax highlighting
            """
            if PYGMENTS_AVAILABLE and language:
                try:
                    # Get the appropriate lexer for the language
                    lexer = get_lexer_by_name(language, stripall=False)
    
                    # Use Pygments to tokenize and highlight
                    from pygments import lex
                    from pygments.token import Token
    
                    lines = code.split('\n')
                    html_lines = []
    
                    for line_num, line in enumerate(lines, 1):
                        # Tokenize this line
                        tokens = list(lex(line + '\n', lexer))
                        highlighted_parts = []
    
                        for token_type, value in tokens:
                            # Skip the newline at the end
                            if value == '\n':
                                continue
    
                            # Escape HTML in the value
                            value = (value
                                    .replace('&', '&amp;')
                                    .replace('<', '&lt;')
                                    .replace('>', '&gt;'))
    
                            # Map Pygments token types to our CSS classes
                            css_class = MarkdownProcessor._get_token_css_class(token_type)
    
                            if css_class:
                                highlighted_parts.append(f'<span class="{css_class}">{value}</span>')
                            else:
                                highlighted_parts.append(value)
    
                        # Add line number and content
                        html_lines.append(
                            f'<span class="line-number">{line_num:3d}</span>'
                            f'<span class="line-content">{"".join(highlighted_parts)}\n</span>'
                        )
    
                    # Build final HTML
                    safe_lang = re.sub(r'[^a-zA-Z0-9_-]', '', language)
                    lang_class = f' language-{safe_lang}' if safe_lang else ''
                    return f'<pre class="code-block{lang_class}"><code>{"".join(html_lines)}</code></pre>'
    
                except ClassNotFound:
                    # Language not found, fall back to plain text
                    pass
                except Exception:
                    # Any other error, fall back to plain text
                    pass
    
            # Fallback: no syntax highlighting, just line numbers and escaping
            code = (code
                    .replace('&', '&amp;')
                    .replace('<', '&lt;')
                    .replace('>', '&gt;'))
    
            lines = code.split('\n')
            html_lines = []
    
            for i, line in enumerate(lines, 1):
                html_lines.append(
                    f'<span class="line-number">{i:3d}</span>'
                    f'<span class="line-content">{line}\n</span>'
                )
    
            # Build final HTML
            if language:
                safe_lang = re.sub(r'[^a-zA-Z0-9_-]', '', language)
                lang_class = f' language-{safe_lang}' if safe_lang else ''
            else:
                lang_class = ''
    
            return f'<pre class="code-block{lang_class}"><code>{"".join(html_lines)}</code></pre>'
    
        @staticmethod
        def _get_token_css_class(token_type) -> Optional[str]:
            """
            Map Pygments token types to our CSS classes.
    
            Args:
                token_type: Pygments token type
    
            Returns:
                CSS class name or None
            """
            from pygments.token import Token
    
            # Map token types to our simpler CSS classes
            if token_type in Token.Keyword:
                return 'syn-keyword'
            elif token_type in Token.String:
                return 'syn-string'
            elif token_type in Token.Comment:
                return 'syn-comment'
            elif token_type in Token.Number:
                return 'syn-number'
            elif token_type in Token.Name.Function:
                return 'syn-function'
            elif token_type in Token.Name.Class:
                return 'syn-class'
            else:
                return None
    
    
  • markdown-to-epub/REFERENCE.md8.5 KBb1eb9f0a1309upstream ↗
    # Markdown to EPUB Skill - Technical Reference
    
    Advanced technical documentation for extending and customizing the Markdown to EPUB skill.
    
    ## Module Overview
    
    ### `markdown_processor.py`
    
    Core module for parsing markdown and extracting document structure.
    
    #### Main Classes
    
    **MarkdownProcessor**
    ```python
    processor = MarkdownProcessor()
    result = processor.process(markdown_content)
    ```
    
    Methods:
    - `process(markdown_content: str) -> Dict` - Parse markdown and extract structure
    - `_extract_frontmatter(content: str) -> str` - Extract YAML frontmatter
    - `_extract_metadata(content: str)` - Extract metadata from document headers
    - `_parse_chapters(content: str) -> List[Chapter]` - Parse into chapters
    - `_parse_sections(content: str, min_level: int) -> List[Section]` - Parse sections
    - `_build_toc() -> List[Dict]` - Build table of contents
    - `markdown_to_html(markdown_text: str) -> str` - Convert markdown to HTML
    - `_render_inline(text: str) -> str` - Process inline elements (bold, italic, links)
    
    #### Data Classes
    
    **EbookMetadata**
    ```python
    metadata = EbookMetadata(
        title="My Book",
        author="John Doe",
        language="en",
        date="2025-01-15",
        identifier="unique-id"
    )
    ```
    
    **Chapter**
    ```python
    chapter = Chapter(
        title="Chapter 1",
        content="Introduction text...",
        sections=[Section(...), ...],
        anchor="chapter-1"
    )
    ```
    
    **Section**
    ```python
    section = Section(
        title="Section 1.1",
        level=2,
        content="Section content...",
        anchor="section-1-1"
    )
    ```
    
    ### `epub_generator.py`
    
    EPUB file creation and management using ebooklib.
    
    #### Main Classes
    
    **EPUBGenerator**
    ```python
    generator = EPUBGenerator(metadata)
    success = generator.generate(chapters, output_path)
    ```
    
    Methods:
    - `generate(chapters: List[Chapter], output_path: str) -> bool` - Main generation method
    - `_create_book()` - Initialize EPUB book object
    - `_add_chapters()` - Add chapters to book
    - `_render_chapter(chapter: Chapter) -> str` - Render chapter to XHTML
    - `_render_content(content: str) -> str` - Render markdown content to HTML
    - `_add_style()` - Add CSS styling
    - `_add_toc()` - Generate table of contents
    - `_write_epub(output_path: str)` - Write EPUB file to disk
    
    **Default CSS**
    - Embedded in `EPUBGenerator.DEFAULT_CSS`
    - Customizable by subclassing
    - Responsive design for all screen sizes
    
    #### Convenience Functions
    
    ```python
    # Create EPUB from markdown string
    create_epub_from_markdown(
        markdown_content: str,
        output_path: str,
        title: Optional[str] = None,
        author: Optional[str] = None
    ) -> bool
    ```
    
    ## HTML/XHTML Generation
    
    ### Markdown to HTML Conversion
    
    The `markdown_to_html()` method converts markdown to semantic HTML:
    
    ```python
    markdown = "# Title\n\nSome **bold** text"
    html = MarkdownProcessor.markdown_to_html(markdown)
    # Returns: <h1>Title</h1>\n<p>Some <strong>bold</strong> text</p>
    ```
    
    ### Supported Elements
    
    - **Headers** (H1-H6): `# to ######`
    - **Emphasis**: `**bold**`, `*italic*`, `__bold__`, `_italic_`
    - **Links**: `[text](url)`
    - **Lists**: `- item`, `* item`, `1. item`
    - **Code**: `` `inline` ``, ` ``` ` ` ` (blocks)
    - **Blockquotes**: `> quote`
    - **Horizontal Rules**: `---`, `***`, `___`
    
    ### Special Handling
    
    - HTML escaping: `&`, `<`, `>`, `"`, `'` are automatically escaped
    - Code blocks: Content is escaped and preserved as-is
    - Paragraphs: Double newlines create new `<p>` tags
    - Links: Properly encoded href attributes
    
    ## EPUB Structure
    
    ### Generated File Layout
    
    ```
    metadata.opf          # Package metadata
    nav.xhtml             # EPUB3 navigation
    toc.ncx               # NCBI NCX (compatibility)
    OEBPS/
    ├── chap_001.xhtml    # Chapter files
    ├── chap_002.xhtml
    ├── ...
    ├── style/
    │   └── main.css      # Embedded stylesheet
    └── [other resources]
    ```
    
    ### Metadata Fields
    
    From `EbookMetadata`:
    - **identifier**: Unique ID (auto-generated UUID if not provided)
    - **title**: Book title (required)
    - **language**: Language code (default: "en")
    - **author**: Author name
    - **date**: Publication date (optional)
    
    ### Navigation
    
    - **NCX (Navigation Control File)**: For backward compatibility with older readers
    - **NAV (EPUB3 Navigation Document)**: Standard for EPUB3 readers
    - Automatic generation from chapter/section hierarchy
    
    ## Customization
    
    ### Extending the Classes
    
    **Custom Styling**
    ```python
    class CustomEPUBGenerator(EPUBGenerator):
        CUSTOM_CSS = """/* Your CSS here */"""
    
        def _add_style(self):
            # Custom styling logic
            super()._add_style()
    ```
    
    **Custom Metadata**
    ```python
    metadata = EbookMetadata()
    metadata.title = "My Custom Title"
    metadata.author = "Custom Author"
    generator = EPUBGenerator(metadata)
    ```
    
    **Custom HTML Rendering**
    ```python
    class CustomProcessor(MarkdownProcessor):
        @staticmethod
        def markdown_to_html(markdown_text):
            # Custom conversion logic
            return html
    ```
    
    ### Adding New Markdown Features
    
    1. Extend `markdown_to_html()` in `MarkdownProcessor`
    2. Add parsing logic for new markdown syntax
    3. Return proper HTML equivalent
    4. Test with `test_epub_skill.py`
    
    Example - Add strikethrough support:
    ```python
    # In markdown_to_html()
    text = re.sub(r'~~(.+?)~~', r'<del>\1</del>', text)
    ```
    
    ## Performance Considerations
    
    ### Large Documents
    - Processing is O(n) where n = document length
    - Memory usage: ~3-5x the markdown source size
    - EPUB generation typically < 100ms for 100+ page documents
    
    ### Optimization Tips
    1. **Batch processing**: Process multiple documents in one run
    2. **Chapter splitting**: Break very large documents into smaller files
    3. **Content optimization**: Remove unnecessary whitespace/formatting
    4. **Lazy loading**: Generate EPUBs on-demand rather than precomputing
    
    ## Debugging
    
    ### Enable Debug Output
    
    ```python
    import logging
    logging.basicConfig(level=logging.DEBUG)
    
    processor = MarkdownProcessor()
    result = processor.process(markdown_content)
    ```
    
    ### Common Issues
    
    **Empty chapters**
    - Check that markdown has proper structure
    - Verify no sections have completely empty content
    - Use `_render_content()` to debug HTML output
    
    **Invalid XHTML**
    - Verify all tags are properly closed
    - Check for unescaped special characters
    - Use validator tools on generated EPUB
    
    **Missing TOC**
    - Ensure chapters/sections have proper headers
    - Verify anchor generation works correctly
    - Check that sections list is populated
    
    ## API Integration
    
    ### Using with Claude Skills
    
    ```python
    # In your skill implementation
    def generate_ebook(markdown_content, title=None, author=None):
        from epub_generator import create_epub_from_markdown
    
        success = create_epub_from_markdown(
            markdown_content,
            "output.epub",
            title=title,
            author=author
        )
    
        if success:
            # Return file_id or stream
            return read_epub_file("output.epub")
        else:
            return None
    ```
    
    ### File Handling
    
    The skill can work with:
    - Direct file paths
    - File contents via Files API
    - Markdown strings
    - Chat message content
    
    ## Testing
    
    ### Unit Tests
    
    ```python
    # Test markdown parsing
    processor = MarkdownProcessor()
    result = processor.process(test_markdown)
    assert len(result['chapters']) == expected_count
    
    # Test HTML generation
    html = MarkdownProcessor.markdown_to_html(test_content)
    assert '<h1>' in html
    assert '<strong>' in html
    ```
    
    ### Integration Tests
    
    ```python
    # Test end-to-end EPUB generation
    success = create_epub_from_markdown(
        markdown_content,
        test_output_path,
        title="Test",
        author="Tester"
    )
    assert success
    assert Path(test_output_path).exists()
    ```
    
    ### Test Coverage
    
    Current test coverage:
    - ✓ Markdown parsing with multiple header levels
    - ✓ YAML frontmatter extraction
    - ✓ HTML generation and escaping
    - ✓ EPUB file creation
    - ✓ Edge cases (empty content, special characters)
    - ✓ Table of contents generation
    - ✓ Large documents (100+ chapters)
    
    ## Version History
    
    **v1.0.0** (Current)
    - Initial release
    - Full markdown to EPUB conversion
    - YAML frontmatter support
    - Automatic TOC generation
    - EPUB3 compliance
    - Complete test suite
    
    ## Future Roadmap
    
    **v1.1.0** (Planned)
    - Cover page generation
    - Custom CSS templates
    - Image embedding
    
    **v2.0.0** (Future)
    - Kindle format support (.mobi, .azw3)
    - Advanced table support
    - Footnotes and cross-references
    - Experimental MCP integration for cover images
    
    ## Contributing
    
    ### Code Guidelines
    - Follow PEP 8 style guide
    - Add docstrings to all functions
    - Include type hints
    - Write tests for new features
    - Update this reference documentation
    
    ### Adding Features
    1. Create a feature branch
    2. Implement with tests
    3. Update SKILL.md and REFERENCE.md
    4. Submit with test results
    
    ---
    
    **Last Updated**: 2025-01-16
    **Maintained By**: Skills Development Team
    
  • markdown-to-epub/requirements.txt52 Bad18581eee5eupstream ↗
    ebooklib==0.18.0
    markdown2==2.4.12
    Pygments==2.17.2
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/smerchek-claude-epub-skill-markdown-to-epub.md

// REPO STATS

171 stars
2 open issues
Last commit: 1yr ago