Markdown to EPUB s obsahem kapitol a obalem v jednom API volání

Vydavatelský průmysl strávil desetiletí budováním složitých řetězců nástrojů pro výrobu knih. Rukopisy se pohybovaly od textových editorů přes software pro rozvržení stránek k generátorům PDF až po tiskově připravené soubory prostřednictvím potrubí, které zahrnovalo více specialistů a více licencí software v každé fázi. Když přišly e-knihy, potrubí získalo další složitost spíše než zjednodušení: tentýž rukopis nyní potřeboval vytvářet jak tiskově připravené PDF, tak reflowable EPUBY, formáty s fundamentálně odlišnými filosofiemi o tom, jak by měl být obsah prezentován. Tiskový formát všechno zamyká. Formát e-knihy všechno nechá proudit. Vytváření obojího z jednoho zdroje je problém, který tradiční vydavatelský řetězec řeší se vší elegancí patchworkové přikrývky.

Pisatelé, kteří sami vydávají, čelí této složitosti řetězce bez institucionální podpory, kterou poskytují tradiční vydavatelé. Rukopis existuje jako dokument Word nebo Google Doc. Převedení na správně formátovaný EPUB vyžaduje buď naučit se specializovaný software pro produkci e-knih (Calibre, Sigil, Vellum), nebo zaplatit formátovači, který si účtuje za projekt. Krok formátování, který nepřidává kreativní hodnotu knize, se stává úzkým místem mezi dokončením rukopisu a jeho zpřístupněním čtenářům. Pro autory vydávající více knih je kumulativní náklady a čas tohoto kroku formátování významné a zcela předvídatelné, což jej činí ideálním kandidátem na automatizaci.

API Ebooks API redukuje celý proces konverze na jeden API hovor. Pište knihu v Markdownu, což je formát, který může vytvářet jakýkoli textový editor a kterým se může naučit každý pisatel za deset minut. Pošlete obsah Markdownu společně s metadaty a volitelným obalem. Obdržíte profesionální soubor EPUB se strukturovaným obsahem, správně vymezených kapitolami, vloženým obalem a všemi metadaty, která vyžadují prodejci e-knih a knihovny. Jeden vstup, jeden hovor, jeden výstup. Celý vydavatelský řetězec komprimovaný do HTTP požadavku.

Proč je Markdown ideálním formátem pro psaní knih

Vhodnost Markdownu pro psaní knih není ihned patrná pisatelům zvyklým na editory bohatého textu. Formát vypadá jednoduše, téměř primitivně, ve srovnání s formátovaným zobrazením v aplikaci Word nebo Google Docs. Ale tato zdánlivá jednoduchost je právě její silou pro dlouhé psaní. Markdown zcela odděluje obsah od prezentace, což znamená, že pisatel se soustředí na to, co říká, aniž by byl rozptylován nebo omezen tím, jak to bude vypadat. Rozhodnutí o prezentaci se uskutečňují později během procesu konverze, kde mohou být aplikovány konzistentně a měněny hromadně bez dotýkání se rukopisu.

Nadpisy kapitol v Markdownu jsou označeny symboly hash. Jeden hash označuje název knihy. Dvojité hashe označují názvy kapitol. Trojité hashe označují nadpisy sekcí v kapitolách. Tato hierarchická struktura se mapuje přímo na strukturu navigace EPUB: názvy kapitol se stanou položkami obsahu, nadpisy sekcí se stanou podpoložkami a název knihy se stane prvkem navigace nejvyšší úrovně. Pisatel vytváří strukturu knihy prostým označením nadpisů a API tuto strukturu automaticky překládá do navigačního rámce EPUB.

Odstavce jsou odděleny prázdnými řádky. Důraz je označen hvězdičkami. Blokové citáty jsou označeny úhlovými závorkami. Odkazy jsou označeny hranatými závorkami a závorkami. Každá z těchto konvencí Markdownu má přímý ekvivalent v interním HTML EPUB a konverze je deterministická: stejný vstup Markdownu vždy vytváří stejnou strukturu EPUB. Tato předvídavost je důležitá pro autory, kteří vydávají revize nebo aktualizované vydání, protože změny Markdownu přináší odpovídajícím se změnám v EPUB bez zavedení vedlejších účinků formátování.

Přenositelnost souborů Markdown je další významná výhoda. Rukopis napsaný v Markdownu je prostý textový soubor, který lze otevřít, upravit a ovládat verzi pomocí jakéhokoli nástroje v jakémkoli operačním systému. Není vázán na konkrétní verzi textového procesoru, nevyžaduje konkrétní licenci na software pro přístup a nesnižuje se v průběhu času, když se formáty software vyvíjejí. Rukopis Markdown napsaný dnes bude čitelný přesně stejnou formou za deset nebo dvacet let, což se nedá říci o žádném proprietárním formátu dokumentu. Pro autory, kteří plánují udržovat a aktualizovat svá díla po dlouhou dobu, je tato dlouhověkost formátu smysluplnou výhodou.

Metadata a co dělá EPUB profesionální

Profesionální soubor EPUB obsahuje více než jen obsah knihy. Obsahuje metadata, která popisují knihu systémům, které ji distribuují, katalogizují a zobrazují. Název, autor, vydavatel, jazyk, datum publikace, ISBN, popis a kategorie předmětu jsou všechny vloženy do souboru EPUB jako strukturovaná metadata, která prodejci e-knih, knihovnické systémy a čtecí aplikace používají k řádné katalogizaci a zobrazení knihy.

API přijímá tato metadata spolu s obsahem Markdownu a vkládá je do EPUB podle specifikace OPF (Open Packaging Format), která definuje, jak by měla být strukturována metadata EPUB. Metadata nejsou jen vložena do hlavičky souboru; je formátován podle standardů metadat Dublin Core, které EPUB používá, se správnými typy prvků, atributy a deklaracemi oboru názvů, které očekávají validační nástroje a maloobchodní platformy. EPUB se správně strukturovanými metadaty je přijímán Amazon KDP, Apple Books, Kobo, Google Play Books a každou jinou hlavní maloobchodní platformou bez změny.

Obraz obalu je obzvláště důležitý prvek metadat, protože je to první věc, kterou vidí potenciální čtenář v jakémkoli maloobchodním prostředí. API přijímá soubor obalem (JPEG nebo PNG) a vkládá jej do EPUB se správnými záznamy manifestu, odkazy páteře a deklaracemi metadat, které způsobují, že čtecí aplikace jej zobrazují jako obálku knihy. Obrázek je také změněn na velikost a optimalizován, je-li to potřeba, aby splnil požadavky na rozměr a velikost souboru, které maloobchodní platformy ukládají, čímž se zajistí, aby byl EPUB prodejný bez ruční zpracování obrázků.

Vložení ISBN si zaslouží zvláštní zmínku, protože je to identifikátor, který připojuje knihu k globální infrastruktuře obchodu s knihami. EPUB se správně vloženým ISBN lze katalogizovat v knihovnách, sledovat maloobchodníci, odkazovat na ně weby s recenzemi a jednoznačně identifikovat v jakémkoli kontextu, kde se knihy diskutují nebo prodávají. API vkládá ISBN do metadat EPUB pomocí formátu určeného Mezinárodní agenturou pro ISBN a zajišťuje kompatibilitu se systémy, které používají ISBN pro identifikaci a správu katalogů.

Obsah a struktura kapitol

Obsah v EPUB slouží dvěma funkcím, které se liší od obsahu vytištěné knihy. V tištěné knize je obsah stránkou, která obsahuje názvy kapitol a čísla stránek. V EPUB je obsah navigačním prvkem, který umožňuje přímé skočení na jakoukoli kapitolu nebo sekci, a je zobrazen navigačním rozhraním čtecí aplikace spíše než jako vykreslená stránka. Dobře strukturovaný obsah EPUB dělá knihu navigovatelnou stejně jako dobře strukturovaný web je navigovatelný: čtenáři mohou skočit přímo na jakoukoli kapitolu bez scrollování přes celou knihu postupně.

API generuje obsah ze struktury nadpisů v obsahu Markdownu. Každý nadpis druhé úrovně (dvojitý hash) se stane položkou kapitoly v obsahu. Každý nadpis třetí úrovně (trojitý hash) se stane podpoložkou pod svou nadřazenou kapitolou. Tato dvoustupňová navigační struktura poskytuje dostatečnou granularitu pro většinu knih bez přetížení navigačního rozhraní nadměrným počtem dílčích položek. Obsah je generován jak navigačním prvkem (NCX pro kompatibilitu EPUB2 a Navigation Document pro EPUB3), což zajišťuje, že kniha funguje správně v starších elektronických čtečkách a také v moderních čtecích aplikacích.

Zlomy kapitol v generovaném EPUB odpovídají nadpisům druhé úrovně v Markdownu. Každá kapitola začíná na nové stránce v elektronické čtečce, což poskytuje vizuální oddělení mezi kapitolami, které čtenáři očekávají. API vkloňuje příslušné konce stránek XHTML a položky páteře, aby zajistilo, že elektronické čtečky považují každou kapitolu za odlišnou jednotku navigace spíše než nepřetržité posouvání. Toto oddělení kapitol také umožňuje elektronickým čtečkám zobrazovat názvy kapitol v ukazateli pokroku čtení a ukazovat čtenáři, kterou kapitolu právě čte a jak daleko v ní pokročil.

Pro knihy se složitými strukturami, jako jsou části obsahující více kapitol, dodatky nebo sekce předmluviny, hierarchie nadpisů Markdownu přirozeně vychází těmto strukturám vstříc. Nadpisy první úrovně mohou označovat části, nadpisy druhé úrovně označují kapitoly v částech a nadpisy třetí úrovně označují sekce v kapitolách. API mapuje tuto hierarchii na navigační strukturu EPUB věrně a vytváří obsah, který odráží organizační logiku knihy bez ohledu na to, kolik úrovní vnoření autor používá.

Jeden hovor a jak vypadá požadavek API

Hovor API, který vytváří EPUB, je žádost POST obsahující obsah Markdownu, pole metadat a volitelně soubor obalu. Obsah Markdownu je tělem knihy, označeným nadpisy, odstavci a jakýmikoli dalšími prvky Markdownu, které autor používá. Pole metadat jsou páry klíč-hodnota: název, autor, jazyk, popis, ISBN, datum publikace a všechna další pole Dublin Core, která chce autor zahrnout. Obraz obalu, je-li poskytnut, je nahrán jako příloha souboru.

Odpověď je soubor EPUB sám o sobě, připravený ke stažení, distribuce nebo nahrání na maloobchodní platformu. Soubor je v souladu se specifikací EPUB 3 s zpětnými záložkami kompatibility EPUB 2, což zajišťuje, že funguje na každé moderní elektronické čtečce a čtecí aplikaci, stejně jako na starších zařízeních, která podporují pouze starší standard. Soubor projde validací EPUB (epubcheck) bez chyb, což je požadavek pro odeslání do většiny maloobchodních platforem a silný ukazatel strukturální správnosti.

Pro autory s více knihami nebo více vydáními lze hovor API integrovat do automatizovaného vydavatelského potrubí. Rukopis Markdown je uložen v ovládání verzí (Git, například), metadata jsou uložena v konfiguračním souboru a skript build odesílá obojí do API, kdykoli je potřeba vytvořit novou verzi. Toto automatizované potrubí znamená, že opravy, aktualizace a nová vydání mohou být vytvořena a distribuována během minut spíše než hodin nebo dnů, které vyžadují ruční pracovní postupy formátování. Oprava literární chyby trvá třicet sekund: upravit Markdown, spustit skript build, nahrát nový EPUB na maloobchodní platformu.

Jednoduchost volání API skrývá složitost operací, které se za ním odehrávají. API analyzuje Markdown, generuje obsah souborů XHTML pro každou kapitolu, vytváří manifest OPF a páteř, generuje NCX a Navigation Document, vkládá a odkazuje na obraz obalu, strukturuje všechna metadata podle standardů Dublin Core a EPUB, balí vše do formátu kontejneru EPUB (což je vlastně speciálně strukturovaný soubor ZIP) a ověřuje výsledek proti specifikaci EPUB. Všechny tyto operace, z nichž každá představuje potenciální bod selhání v ruční produkci EPUB, jsou zpracovávány automaticky a spolehlivě pokaždé.