Markdown To Epub Converter

# 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