{
  "markdown": "# Markdown to EPUB Claude Skill\n\nA 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.\n\n## Overview\n\nThis skill transforms markdown content into EPUB3 format ebooks that work across all major reading platforms:\n- Apple Books\n- Amazon Kindle (via Kindle reading apps)\n- Google Play Books\n- Kobo\n- Any standard EPUB reader\n\n## Features\n\n✨ **Markdown Processing**\n- Automatic chapter detection from H1 headers\n- Automatic section parsing from H2-H6 headers\n- Full markdown formatting support (bold, italic, links, lists, code blocks, etc.)\n- **Enhanced code blocks** with premium monospace fonts and syntax highlighting support\n- **Professional tables** with styled headers and alternating row colors\n\n📚 **EPUB Generation**\n- EPUB3 standard compliance\n- Automatic table of contents with proper navigation\n- Responsive, device-agnostic styling\n- Proper document structure and metadata\n- Beautiful code formatting for technical documents\n\n🎯 **Smart Input Handling**\n- Accept raw markdown text directly\n- Process markdown files by path\n- Extract metadata from YAML frontmatter\n- Handle edge cases gracefully\n\n## Project Structure\n\n```\nmarkdown-to-epub/\n├── SKILL.md                    # Skill definition with YAML frontmatter\n├── requirements.txt            # Python dependencies\n├── scripts/\n│   ├── markdown_processor.py  # Markdown parsing & structure extraction\n│   ├── epub_generator.py      # EPUB file creation & formatting\n└── resources/\n    └── default_styles.css     # (future) Custom EPUB styling\ntest_epub_skill.py             # Test suite with sample content\n```\n\n## Installation\n\n### Prerequisites\n- Python 3.8+\n- pip (Python package manager)\n\n### Setup\n\n1. **Install dependencies:**\n   ```bash\n   pip install -r markdown-to-epub/requirements.txt\n   ```\n\n2. **Verify installation:**\n   ```bash\n   python test_epub_skill.py\n   ```\n\n   You should see all tests pass:\n   - ✓ Markdown processing: PASSED\n   - ✓ EPUB generation: PASSED\n   - ✓ Edge cases: PASSED\n\n## Usage\n\n### Basic Python Usage\n\n```python\nfrom markdown_to_epub.scripts.epub_generator import create_epub_from_markdown\n\nmarkdown_content = \"\"\"\n# My Book\n\n## Chapter 1\nContent here...\n\"\"\"\n\n# Generate EPUB\ncreate_epub_from_markdown(\n    markdown_content,\n    output_path=\"my_book.epub\",\n    title=\"My Book\",\n    author=\"John Doe\"\n)\n```\n\n### With Claude Skills Framework\n\nWhen registered as a Claude skill, simply ask Claude to convert markdown to EPUB:\n\n```\n\"Convert this markdown to an EPUB ebook:\n# Research Summary\n## Introduction\n...content...\"\n```\n\nOr provide a file path:\n\n```\n\"Convert the markdown file at research_notes.md to an EPUB file\"\n```\n\n## Markdown Support\n\n| Element | Example | Support | Styling |\n|---------|---------|---------|---------|\n| Headers | `# H1` through `###### H6` | Full | Optimized sizes for e-readers |\n| Bold | `**bold**` or `__bold__` | Full | Strong emphasis |\n| Italic | `*italic*` or `_italic_` | Full | Subtle emphasis |\n| Links | `[text](url)` | Full | Clickable |\n| Lists | `- item` or `1. item` | Full | Proper indentation |\n| Code Blocks | ` ```language ` | **Enhanced** | Monospace fonts, styled backgrounds, blue accent |\n| Inline Code | `` `code` `` | **Enhanced** | Gray background, subtle border |\n| Tables | Markdown tables | **Enhanced** | Blue headers, zebra striping, responsive |\n| Blockquotes | `> quote` | Full | Blue left border |\n| Horizontal Rule | `---` or `***` | Full | Subtle divider |\n| Paragraphs | Text with blank lines | Full | Justified text |\n\n## YAML Frontmatter Support\n\nAdd metadata to your markdown using YAML frontmatter:\n\n```markdown\n---\ntitle: My Ebook\nauthor: John Doe\nlanguage: en\ndate: 2025-01-15\n---\n\n# Chapter 1\n...\n```\n\nSupported fields:\n- `title` - Book title\n- `author` - Author name\n- `language` - Language code (default: `en`)\n- `date` - Publication date\n\n## Architecture\n\n### MarkdownProcessor (`markdown_processor.py`)\n- Parses markdown into structured chapters and sections\n- Extracts metadata from YAML frontmatter\n- Builds table of contents\n- Converts markdown to HTML\n- Handles edge cases (empty content, special characters, etc.)\n\n### EPUBGenerator (`epub_generator.py`)\n- Creates valid EPUB3 files using ebooklib\n- Manages book metadata and document structure\n- Applies consistent styling via embedded CSS\n- Generates navigation documents (NCX, NAV)\n- Handles proper spine/TOC setup\n\n## Dependencies\n\n- **ebooklib** (0.18.0) - EPUB file creation and manipulation\n- **markdown2** (2.4.12) - Markdown utilities (included for future enhancement)\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\npython test_epub_skill.py\n```\n\nTests include:\n- Markdown parsing with various header structures\n- EPUB file generation and validation\n- Edge cases (empty content, plain text, special characters)\n- Long documents (10+ chapters)\n- Table of contents generation\n- Metadata extraction\n\n## Future Enhancements\n\n🎨 **Cover Page Generation**\n- Auto-generate title pages with styling\n- Custom cover images with MCP integration\n\n📱 **Kindle Support**\n- .mobi and .azw3 format generation\n- Kindle-specific optimizations\n- Direct Kindle device upload capability\n\n🎨 **Advanced Styling**\n- Custom CSS per user preferences\n- Custom fonts\n- Advanced typography controls\n\n📚 **Multi-Document**\n- Merge multiple markdown files\n- Cross-document references\n- Advanced chapter organization\n\n## Technical Details\n\n- **EPUB Version**: EPUB3 (2023 standard)\n- **HTML Standard**: XHTML 1.1\n- **Character Encoding**: UTF-8\n- **CSS Support**: Responsive, embedded styling\n- **Navigation**: NCX (compatibility) + NAV (EPUB3 standard)\n\n## Troubleshooting\n\n**EPUB won't open**\n- Verify markdown uses proper syntax\n- Check for balanced brackets in links\n- Ensure chapters have H1 headers\n\n**Missing table of contents**\n- Add H1 headers to mark chapter boundaries\n- Verify headers are followed by content\n\n**Formatting looks different**\n- This is normal! EPUB readers apply their own fonts and styling\n- Structure is preserved across all readers\n\n**Large file size**\n- Compress with external tools if needed\n- Remove large embedded content if applicable\n\n## License\n\nThis skill follows the same license as the Claude Cookbooks project.\n\n## Contributing\n\nContributions are welcome! Areas for improvement:\n- Additional markdown features (tables, footnotes)\n- Enhanced styling options\n- Performance optimizations\n- Additional format support\n\n## Related Resources\n\n- [EPUB 3 Standard](https://www.w3.org/publishing/epub32/)\n- [Claude Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/)\n- [ebooklib Documentation](https://docs.sourcefabric.org/projects/ebooklib/)\n- [Markdown Syntax](https://www.markdownguide.org/)\n\n---\n\n**Created**: 2025-01-16\n**Version**: 1.0.0\n**Status**: Production Ready\n",
  "bytes": 6938,
  "sha": "84f21350a934cb4fb9de096448a7247afebf187d4ce5f671ae5329224dfb98bb",
  "repo_slug": "smerchek/claude-epub-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_smerchek_claude_epub_skill_markdown_to_e_2e300d77/readme"
}