book2md

book2md é uma ferramenta para transformar livros digitais em artefatos Markdown organizados por capítulo.

O objetivo da aplicação, como um todo, é converter arquivos .epub e .pdf textuais em uma saída local simples, legível e reutilizável para estudo, revisão, arquivamento, busca e processamento posterior. Em vez de entregar um bloco único de texto, o projeto prioriza uma estrutura prática de trabalho: capítulos em .md, metadados normalizados e, quando solicitado, assets associados como imagens.

Para quem é

book2md é útil para quem quer:

• estudar livros em Markdown, capítulo por capítulo
• versionar ou anotar conteúdo exportado em filesystem local
• alimentar pipelines locais de indexação, busca ou processamento textual
• inspecionar a estrutura lógica de um livro com TOC e metadata preservados

O que a aplicação entrega

Uma exportação bem-sucedida pode gerar:

• um arquivo Markdown por capítulo, com nomes ordenáveis
• metadata.json com informações estruturadas do livro, TOC e origem da segmentação
• diretório images/ com assets exportados quando --include-images é usado
• preview local para inspeção rápida dos artefatos gerados

Instalação

pip install -e .

Uso rápido

book2md export-epub livro.epub --output ./saida
book2md export-epub livro.epub --output ./saida --include-images
book2md preview ./saida

Fluxo básico

1. exporte o livro para um diretório de saída
2. revise os capítulos Markdown gerados
3. consulte metadata.json para TOC, origem da segmentação e dados do livro
4. use preview para uma inspeção local rápida, quando necessário

Artefatos gerados

O contrato de saída está documentado em docs/architecture/METADATA_JSON.md.

Na prática, a exportação produz:

• arquivos .md por capítulo
• metadata.json com contrato documentado em docs/architecture/METADATA_JSON.md
• opcionalmente images/ quando --include-images é usado

Papel do repositório book2md

kb é a implementação principal (source of truth) para a lógica de importação/exportação de livros.

Dentro dessa arquitetura, o repositório book2md existe para:

• oferecer uma experiência CLI focada no caso de uso de exportação
• validar o contrato dos artefatos exportados
• manter testes espelho e fixtures menores
• reduzir divergência entre laboratório e implementação principal

Em outras palavras: a lógica central mora em kb, enquanto book2md empacota, testa e valida a experiência de uso dessa capacidade.

Preview local

O comando book2md preview <diretório-exportado> abre um servidor local simples para inspecionar:

• capítulos exportados
• metadata.json
• origem do TOC e da segmentação
• assets exportados