Markdown til EPUB med indholdsfortegnelse, kapitler og omslag i et API-kald

Forlagsindustrien brugte årtier på at opbygge sofistikerede værktøjskæder til bogproduktion. Manuskripter blev flyttet fra ordprocessorer gennem sidelayoutsoftware til PDF-generatorer til trykkeklar filer gennem et flow, der involverede flere specialister og flere softwarelicenser i hver fase. Da e-bøger ankom, fik flowet yderligere kompleksitet i stedet for at blive forenklet: samme manuskript skulle nu producere både trykkeklar PDF og reflowable EPUB, formater med fundamentalt forskellige filosofier om, hvordan indhold skal præsenteres. Tryktformatet låser alt på plads. E-bogformatet lader alt flyde. At producere begge fra en enkelt kilde er et problem, som den traditionelle forlagsværktøjskæde håndterer med al elegancen af et lappetæppe.

Forfattere, der selv udgiver, står over for denne værktøjskædekompleksitet uden den institutionelle støtte, som traditionelle forlag giver. Manuskriptet eksisterer som et Word-dokument eller Google Doc. Konvertering til en korrekt formateret EPUB kræver enten at lære specialized e-bogsproduktionssoftware (Calibre, Sigil, Vellum) eller at betale en formattør, der tager betaling pr. projekt. Formatteringstrinnet, som ikke tilføjer kreativ værdi til bogen, bliver en flaskehals mellem afslutning af manuskriptet og gøring af det tilgængeligt for læsere. For forfattere, der udgiver flere bøger, er de kumulative omkostninger og tid for dette formatteringstrin betydelige og helt forudsigelige, hvilket gør det til en ideel kandidat til automatisering.

Ebooks API reducerer hele konverteringsprocessen til et enkelt API-kald. Skriv bogen i Markdown, som er et format, som enhver teksteditor kan producere, og som enhver forfatter kan lære på ti minutter. Send Markdown-indhold sammen med metadata og et valgfrit omslag. Modtag en professionel EPUB-fil med en struktureret indholdsfortegnelse, korrekt afgrænsede kapitler, indlejret omslag og alle de metadata, som e-bogforhandlere og biblioteker kræver. Ét input, ét kald, ét output. Hele forlagsværktøjskæden komprimeret til en HTTP-anmodning.

Hvorfor Markdown er det ideelle forfatterskab for bøger

Markdowns egnethed til bogskrivning er ikke umiddelbart indlysende for forfattere, der er vant til ordbehandlere. Formatet ser enkelt ud, næsten primitivt, sammenlignet med det formaterede syn i Word eller Google Docs. Men denne tilsyneladende enkelhed er præcis dens styrke for langtekstskrivning. Markdown adskiller indhold fra præsentation fuldstændigt, hvilket betyder, at forfatteren fokuserer på hvad de siger uden at blive distraheret eller begrænset af hvordan det vil se ud. Præsentationsbeslutningerne sker senere under konverteringsprocessen, hvor de kan anvendes konsistent og ændres fuldstændigt uden at røre ved manuskriptet.

Kapitelheder i Markdown er markeret med hash-symboler. Et enkelt hash angiver bogtitlen. Dobbelt hash angiver kapiteltitler. Tredobbelt hash angiver sektionsoverskrifter inden for kapitler. Denne hierarkiske struktur mapper direkte til EPUBs navigationsstruktur: kapiteltitler bliver indholdsfortegnelsesposter, sektionsoverskrifter bliver underposter, og bogtitlen bliver det øverste navigationselement. Forfatteren skaber bogens struktur ved blot at markere overskrifter, og API'en oversætter denne struktur til EPUBs navigationrammeverk automatisk.

Afsnit adskilles med tomme linjer. Vægt er markeret med asterisker. Blokcitater er markeret med vinklede parenteser. Links markeres med firkantede parenteser og parenteser. Hver af disse Markdown-konventioner har en direkte ækvivalent i EPUBs indre HTML, og konverteringen er deterministisk: det samme Markdown-input producerer altid samme EPUB-struktur. Denne forudsigelighed er vigtig for forfattere, der udgiver revisioner eller opdaterede udgaver, fordi ændringer i Markdown producerer tilsvarende præcise ændringer i EPUB uden at introducere formateringsbieffekter.

Portabiliteten af Markdown-filer er en anden betydelig fordel. Et manuskript skrevet i Markdown er en almindelig tekstfil, som kan åbnes, redigeres og versionskontrolleres med ethvert værktøj på ethvert operativsystem. Det er ikke låst til en specifik ordprocessorversion, kræver ikke en specifik softwarelicens for adgang og degraderer ikke over tid, når softwareformater udvikler sig. Et Markdown-manuskript skrevet i dag vil være læseligt på præcis samme måde om ti eller tyve år, hvilket ikke kan siges om nogen proprietær dokumentformat. For forfattere, der planlægger at vedligeholde og opdatere deres værker over lange perioder, er denne formatalderdom en meningsfuld fordel.

Metadata og hvad der gør en EPUB professionel

En professionel EPUB-fil indeholder mere end blot bogens indhold. Den indeholder metadata, der beskriver bogen til de systemer, der distribuerer, katalogiserer og viser den. Titel, forfatter, forlag, sprog, udgivelsesdato, ISBN, beskrivelse og fagkategorier er alle indlejret i EPUB-filen som struktureret metadata, som e-bogforhandlere, bibliotekssystemer og læseprogrammer bruger til korrekt katalogisering og visning af bogen.

API'en accepterer disse metadata ved siden af Markdown-indholdet og indlejrer dem i EPUB i henhold til OPF-specifikationen (Open Packaging Format), som definerer, hvordan EPUB-metadata skal struktureres. Metadata er ikke blot indsat i en filheader; den er formateret i henhold til Dublin Core-metadatastandarderne, som EPUB bruger, med rigtige elementtyper, attributter og navnerumsdeklarationer, som valideringsværktøjer og detailhandelsplatforme forventer. En EPUB med korrekt struktureret metadata accepteres af Amazon KDP, Apple Books, Kobo, Google Play Books og alle andre store detailhandelsplatforme uden ændring.

Omslagsbilledet er et særlig vigtig metadataelement, fordi det er det første, en potentiel læser ser i ethvert detailhandelmiljø. API'en accepterer en omslagsbilledfil (JPEG eller PNG) og indlejrer den i EPUB med de rigtige manifestposter, spinereferences og metadatadeklarationer, der får læseprogrammer til at vise det som bogens omslag. Billedet ændres også i størrelse og optimeres om nødvendigt for at opfylde de dimensions- og filstørrelses krav, som detailhandelsplatforme pålægger, hvilket sikrer, at EPUB er detailhandelsklart uden manuel billedbehandling.

ISBN-indlejring fortjener særlig omtale, fordi det er det identifikator, der forbinder bogen til den globale boghandelinfrastruktur. En EPUB med en korrekt indlejret ISBN kan katalogiseres af biblioteker, spores af detailhandlere, refereres til af anmeldelseswebsteder og identificeres utvetydigt i enhver sammenhæng, hvor bøger diskuteres eller sælges. API'en indlejrer ISBN i EPUBs metadata ved hjælp af det format, som International ISBN Agency angiver, og sikrer kompatibilitet med de systemer, der bruger ISBN til identifikation og katalogadministration.

Indholdsfortegnelse og kapittelstruktur

Indholdsfortegnelsen i en EPUB tjener to funktioner, der er forskellige fra indholdsfortegnelsen i en trykt bog. I en trykt bog er indholdsfortegnelsen en side, der viser kapiteltitler og sidenumre. I en EPUB er indholdsfortegnelsen et navigationselement, der muliggør direkte spring til ethvert kapitel eller sektion, og det vises af læseprogrammets navigationgrænseflade i stedet for som en gengivet side. En velstruktureret EPUB-indholdsfortegnelse gør bogen navigerbar på samme måde som et velstruktureret websted er navigerbart: læsere kan springe direkte til ethvert kapitel uden at scrolle gennem hele bogen sekventielt.

API'en genererer indholdsfortegnelsen fra overskriftsstrukturen i Markdown-indholdet. Hver overskrift på niveau to (dobbelt hash) bliver en kapitelpost i indholdsfortegnelsen. Hver overskrift på niveau tre (tredobbelt hash) bliver en underpost under sin overordnede kapitel. Denne totrinsnavigation struktur giver tilstrækkelig granularitet for de fleste bøger uden at overvælde navigationgrænsefladen med overdrevne underposter. Indholdsfortegnelsen genereres både som et navigationselement (NCX til EPUB2-kompatibilitet og Navigation Document til EPUB3), hvilket sikrer, at bogen fungerer korrekt på ældre e-læsere såvel som moderne læseprogrammer.

Kapitelskift i det genererede EPUB svarer til niveau-to-overskrifterne i Markdown. Hvert kapitel starter på en ny side i e-læseren, hvilket giver den visuelle adskillelse mellem kapitler, som læsere forventer. API'en indsætter de passende XHTML-sideskift og spineposter for at sikre, at e-læsere behandler hvert kapitel som en særskilt navigationsenhed i stedet for kontinuerligt scroll. Denne kapitelopdeling gør det også muligt for e-læsere at vise kapiteltitler i læseprogressindikatoren, hvilket viser læseren, hvilket kapitel de læser, og hvor langt de er kommet i det.

For bøger med komplekse strukturer, såsom dele indeholdende flere kapitler, appendikser eller forordprologs-sektioner, imødekommer Markdown-overskriftshierarkiet disse strukturer naturligt. Niveau-en-overskrifter kan betegne dele, niveau-to-overskrifter angiver kapitler inden for dele, og niveau-tre-overskrifter angiver sektioner inden for kapitler. API'en kortlægger dette hierarki til EPUBs navigationstruktur trofast og producerer en indholdsfortegnelse, der afspejler bogens organisatoriske logik, uanset hvor mange indlejringsniveauer forfatteren bruger.

Ét kald og hvordan API-anmodningen ser ud

Det API-kald, der producerer EPUB, er en POST-anmodning indeholdende Markdown-indhold, metadatafelter og eventuelt en omslagsbilledfil. Markdown-indholdet er body af bogen, markeret med overskrifter, afsnit og andre Markdown-elementer, som forfatteren bruger. Metadatafelt er nøgle-værdi-par: titel, forfatter, sprog, beskrivelse, ISBN, udgivelsesdato og alle yderligere Dublin Core-felter, som forfatteren ønsker at inkludere. Omslagsbilledet er, hvis det leveres, uploadet som en filvedhæftelse.

Svaret er EPUB-filen selv, klar til download, distribution eller upload til en detailhandelsplatform. Filen er i overensstemmelse med EPUB 3-specifikationen med EPUB 2-kompatibilitetsfallbacks, hvilket sikrer, at den fungerer på alle moderne e-læsere og læseprogrammer såvel som på ældre enheder, der kun understøtter den tidligere standard. Filen passerer EPUB-validering (epubcheck) uden fejl, som er et krav til indsendelse til de fleste detailhandelsplatforme og en stærk indikator af strukturel korrekthed.

For forfattere med flere bøger eller flere udgaver kan API-kaldet integreres i et automatiseret udgivelsesflow. Markdown-manuskriptet gemmes i versionskontrol (Git, for eksempel), metadata gemmes i en konfigurationsfil, og et build-script sender begge til API'en, når der skal genereres en ny version. Dette automatiserede flow betyder, at rettelser, opdateringer og nye udgaver kan produceres og distribueres på få minutter i stedet for de timer eller dage, som manuelle formateringsflows kræver. En stavefejl rettelse tager tredive sekunder: rediger Markdown, kør build-scriptet, upload den nye EPUB til detailhandelsplatformen.

Enkelheden af API-kaldet skjuler kompleksiteten af de operationer, der sker bag den. API'en analyserer Markdown, genererer XHTML-indholdsfiler for hvert kapitel, opretter OPF-manifest og -spine, genererer NCX og Navigation Document, indlejrer og refererer omslagsbilledet, strukturerer alle metadata i henhold til Dublin Core og EPUB-standarder, pakker alt i EPUB-containerformatet (som faktisk er en specielt struktureret ZIP-fil) og validerer resultatet mod EPUB-specifikationen. Alle disse operationer, som hver repræsenterer et potentielt fejlpunkt i manuel EPUB-produktion, håndteres automatisk og pålideligt hver gang.