Markdown EPUB:ksi sisällysluettelon, lukujen ja kannen avulla yhdessä API-kutsussa

Kustannusteollisuus käytti vuosikymmeniä kehittämällä monimutkaisia työkaluryhmiä kirjan tuotantoon. Käsikirjoitukset siirtyivät tekstinkäsittelyohjelmista sivun asettelun kautta PDF-generaattoreiden kautta tulostimen valmiisiin tiedostoihin putkijohdon kautta, joka sisälsi useita asiantuntijoita ja useita ohjelmistolisenssejä jokaisessa vaiheessa. Kun e-kirjat saapuivat, putkilinja ei yksinkertaistunut vaan tuli monimutkaisemmaksi: sama käsikirjoitus oli nyt tuotettava sekä tulostin-valmiit PDF:t että reflowable EPUB:t, formaatit, joilla oli perustavanlaatuisesti erilaiset filosofiat siitä, kuinka sisältö tulisi esittää. Tulostinformaatti lukitsee kaiken paikalleen. E-kirjaformaatti antaa kaiken virrata. Molempien tuottaminen yhdestä lähteestä on ongelma, jonka perinteinen kustannustyökaluketju käsittelee kaikella laastarin logiikalla.

Kirjailijat, jotka julkaisevat itse, joutuvat tämän työkaluryhmikompetenssiin ilman institutionaalista tukea, jonka perinteisille kustantamoille tarjolla on. Käsikirjoitus on Word-dokumentti tai Google Doc. Oikein muotoilleen EPUB:ksi muuntaminen vaatii joko erikoistujen e-kirjan tuotanto-ohjelmistojen (Calibre, Sigil, Vellum) oppimista tai muotoilijan palkkaamisen, joka veloittaa projektisuhde. Muotoilu vaihe, joka ei lisää luovaa arvoa kirjaan, tulee pullonkaulaksi käsikirjoituksen valmistumisen ja lukijoille saatavuuden välillä. Kirjailijat, jotka julkaisevat useita kirjoja, tämän muotoiluvaiheensa kumulatiiviset kustannukset ja aika ovat merkittäviä ja täysin ennustettavia, mikä tekee siitä ihanteellisen kandidaatin automatisointi.

Ebooks API vähentää koko muunnosprosessin yhteen API-kutsuun. Kirjoita kirja Markdownissa, joka on formaatti, jonka mikä tahansa tekstieditori voi tuottaa ja jonka mikä tahansa kirjailija voi oppia kymmenessä minuutissa. Lähetä Markdown-sisältö metadatan ja valinnaisen kannen kanssa. Vastaanota ammattimainen EPUB-tiedosto jäsennellyllä sisällysluettelolla, kunnolla erotellut luvut, upotettu kansi ja kaikki metadata, jota e-kirjan myyjät ja kirjastot vaativat. Yksi tulo, yksi kutsu, yksi tulos. Koko kustannustyökaluketju pakattu HTTP-pyyntöön.

Miksi Markdown on ihanteellinen kirjoitusmuoto kirjoille

Markdownin soveltuvuus kirjojen kirjoittamiseen ei ole välittömästi ilmeistä kirjailijoille, jotka ovat tottuneet rikkaaseen tekstinkäsittelyyn. Muoto näyttää yksinkertaiselta, lähes primitiiviseltä verrattuna muotoilluun näkymään Wordissa tai Google Docsissa. Mutta tämä näennäinen yksinkertaisuus on juuri sen vahvuus pitkäkestoisessa kirjoittamisessa. Markdown erottaa sisällön esityksestä kokonaan, mikä tarkoittaa, että kirjailija keskittyy siihen, mitä hän sanoo, ilman että hän häiritsee tai rajoittaa sitä, miten se näyttää. Esityspäätökset tehdään myöhemmin muunnosprosessin aikana, jolloin niitä voidaan soveltaa johdonmukaisesti ja muuttaa kokonaan ilman käsikirjoitukseen koskemista.

Luvun otsikot Markdownissa on merkitty hash-symboleilla. Yksittäinen hash osoittaa kirjan nimen. Kaksinkertainen hash osoittaa luvun otsikoita. Kolminkertainen hash osoittaa osien otsikoita lukujen sisällä. Tämä hierarkinen rakenne kartoittaa suoraan EPUB:n navigointirakenteeseen: luvun otsikot tulevat sisällysluettelo merkinnöiksi, osion otsikot tulevat alapostuksiksi ja kirjan nimi tulee ylimmän navigointielementin. Kirjailija luo kirjan rakenteen yksinkertaisesti merkitsemällä otsikot, ja API kääntää tämän rakenteen EPUB:n navigointikehikkoon automaattisesti.

Kappaleet erotetaan tyhjillä riveillä. Painotus merkitään asteriskeilla. Lohkoksi lainauskset on merkitty kulmikkeilla. Linkit merkitään neliöllisin sulkein ja sulkein. Jokainen näistä Markdown-sopimuksista on suora vastine EPUB:n sisäisessä HTML:ssä ja muunnos on deterministinen: sama Markdown-tulo tuottaa aina saman EPUB-rakenteen. Tämä ennustettavuus on tärkeä kirjailijoille, jotka julkaisevat versioita tai päivitettyjä painoksia, koska Markdown:n muutokset tuottavat vastaavasti tarkkoja muutoksia EPUB:ssa ilman muotoilun sivuvaikutuksia.

Markdown-tiedostojen siirrettävyys on toinen merkittävä etu. Markdownissa kirjoitettu käsikirjoitus on tavallinen tekstiedosto, joka voidaan avata, muokata ja versiohallita millä tahansa työkalulla millä tahansa käyttöjärjestelmällä. Se ei ole sidottu tiettyyn tekstinkäsittelyn versioon, ei vaadi erityistä ohjelmistolopaaa käyttöä varten eikä heikenny ajan myötä, kun ohjelmistoformaatit kehittyvät. Tänään kirjoitettu Markdown-käsikirjoitus on luettavissa täsmälleen samalla tavalla kymmenen tai kahdenkymmenen vuoden kuluttua, mikä ei voi sanoa mistään omistuksellisesta tiedostomuodosta. Kirjailijoille, jotka suunnittelevat teostensa ylläpitoa ja päivittämistä pitkiä aikoja, tämä formaatin pitkäikäisyys on mielekkäällä edulla.

Metadata ja mitä tekee EPUB:n ammattilaiseksi

Ammattimainen EPUB-tiedosto sisältää enemmän kuin vain kirjan sisällön. Se sisältää metadataa, joka kuvaa kirjaa järjestelmille, jotka jakavat sen, luetteloivat sen ja näyttävät sen. Otsikko, kirjailija, kustantaja, kieli, julkaisupäivä, ISBN, kuvaus ja aihekategoriat on kaikki upotettu EPUB-tiedostoon rakennettuina metadatana, joita e-kirjan myyjät, kirjastojärjestelmät ja lukemis-sovellukset käyttävät kirjan luettelointiin ja näyttämiseen.

API hyväksyy nämä metatiedot yhdessä Markdown-sisällön kanssa ja upottaa ne EPUB:iin OPF-spesifikaation (Open Packaging Format) mukaan, joka määrittää, kuinka EPUB-metatiedot tulisi jäsentää. Metatieto ei yksinkertaisesti liimata tiedostonpäähän; se on muotoiltu Dublin Core metatieto-standardien mukaan, joita EPUB käyttää, oikeilla elementtityypeillä, attribuuteilla ja nimiavaruus julistuksilla, joita validointi-työkalut ja vähittäiskauppaplataformit odottavat. EPUB, jossa on asianmukaisesti jäsennelty metatiedot, hyväksytään Amazon KDP:llä, Apple Booksissa, Kobossa, Google Play Booksissa ja jokaisella muulla suurella vähittäiskauppaplataformalla ilman muutoksia.

Kannen kuva on erityisen tärkeä metatieto-elementti, koska se on ensimmäinen asia, jonka potentiaalinen lukija näkee missä tahansa vähittäiskauppapaikassa. API hyväksyy kannen kuvatiedoston (JPEG tai PNG) ja upottaa sen EPUB:iin oikeilla manifest-merkinnöillä, selkä-viitteillä ja metatietojen julistuksilla, jotka saavat lukemis-sovellukset näyttämään sen kirjan kanneksi. Kuva myös muutetaan ja optimoidaan tarpeen mukaan täyttämään vähittäiskauppaplataformien asettamat koko- ja tiedostokokovaatimukset, jotka varmistetaan EPUB on vähittäiskauppaan valmiina ilman manuaalista kuvanprosessointia.

ISBN-upottaminen ansaitsee erityisen maininnon, koska se on tunnus, joka yhdistää kirjan globaaliin kirjakauppaan infrastruktuuriin. EPUB, jonka ISBN on asianmukaisesti upotettu, voidaan luetteloida kirjastoissa, jäljittää jälleenmyyjillä, viitata arvostelusivustoissa ja tunnistaa yksiselitteisesti missä tahansa yhteydessä, jossa kirjoista keskustellaan tai myydään. API upottaa ISBN:n EPUB:n metadataan kansainvälisen ISBN-viraston määrittämässä muodossa ja varmistaa yhteensopivuuden järjestelmien kanssa, jotka käyttävät ISBN:ää tunnistamiseen ja luettelohallintaan.

Sisällysluettelo ja luvun rakenne

Sisällysluettelo EPUB:ssa palvelee kahta toimintoa, jotka eroavat painetun kirjan sisällysluettelosta. Painetussa kirjassa sisällysluettelo on sivu, joka listaa luvun otsikot ja sivunumerot. EPUB:ssa sisällysluettelo on navigointielementti, joka mahdollistaa suoran hyppäämisen mihin tahansa lukuun tai osioon, ja se näytetään lukemis-sovelluksen navigointiliittymässä eikä esitettynä sivuna. Hyvin jäsennelty EPUB-sisällysluettelo tekee kirjasta navigoitavan samalla tavalla kuin hyvin jäsennelty verkkosivusto on navigoitava: lukijat voivat hypätä suoraan mihin tahansa lukuun ilman koko kirjan selausta peräkkäin.

API luo sisällysluettelon Markdown-sisällön otsikkorakenteesta. Jokainen tason kaksi otsikko (kaksinkertainen hash) tulee luvun merkinnöksi sisällysluetteloon. Jokainen tason kolme otsikko (kolminkertainen hash) tulee alamerkinniksi sen ylemmän luvun alla. Tämä kaksitasoinen navigointirakenteen tarjoaa riittävän rakeisuuden useimmille kirjoille ilman navigointiliittymän ylikuormittamista liiallisilla alamerkeillä. Sisällysluettelo luodaan sekä navigointielementtinä (NCX EPUB2-yhteensopivuuden ja Navigation Document EPUB3:lle), mikä varmistaa, että kirja toimii oikein vanhemmissa e-lukijoissa sekä modernissa lukemis-sovelluksissa.

Luvun katkot generoidussa EPUB:ssa vastaavat tason kaksi otsikoita Markdownissa. Jokainen luku alkaa uudella sivulla e-lukijassa, mikä antaa visuaalisen erottelun lukujen välillä, jonka lukijat odottavat. API sisältää asianmukaiset XHTML-sivunkatkot ja selkä-merkinnät varmistaakseen, että e-lukijat käsittelevät jokaista lukua erillään navigointiyksiköinä, ei jatkuvaa selaamista. Tämä luvun erottelu myös antaa e-lukijoille näyttää luvun otsikot luetussa edistymisen ilmaisimessa, ja osoittaa lukijalle, mitä lukua hän parhaillaan lukee ja kuinka pitkälle hän on edennyt siinä.

Kirjoille, joilla on monimutkaisia rakenteita, kuten osat, joissa on useita lukuja, liitteitä tai esipuhe-osia, Markdown-otsikkohierarkia vastaa näistä rakenteista luonnollisesti. Tason yksi otsikot voivat ilmaista osia, tason kaksi otsikot ilmaisevat lukuja osissa ja tason kolme otsikot ilmaisevat osioita luvuissa. API kartoittaa tämän hierarkian EPUB:n navigointirakentteeseen uskollisesti ja tuottaa sisällysluettelon, joka heijastaa kirjan organisatorista logiikkaa riippumatta siitä, kuinka monta pesintätasoa kirjailija käyttää.

Yksi kutsu ja miten API-pyyntö näyttää

API-kutsu, joka tuottaa EPUB:n, on POST-pyyntö, joka sisältää Markdown-sisällön, metatieto-kentät ja valinnaisen kannen kuvatiedoston. Markdown-sisältö on kirjan runko, merkitty otsikoilla, kappaleilla ja muilla Markdown-elementeillä, joita kirjailija käyttää. Metatiedot kentät ovat avain-arvo-pareja: otsikko, kirjailija, kieli, kuvaus, ISBN, julkaisupäivä ja kaikki muut Dublin Core-kentät, jotka kirjailija haluaa sisällyttää. Kannen kuva, jos annettu, on ladattu tiedostoliitteeksi.

Vastaus on EPUB-tiedosto itse, valmis lataamista, jakeluun tai lataamista vähittäiskauppaplataformille. Tiedosto on EPUB 3 -spesifikaation mukainen EPUB 2 -yhteensopivuuden takaisinpalautuksilla, mikä varmistaa, että se toimii kaikissa moderneissa e-lukijoissa ja lukemis-sovelluksissa sekä vanhemmissa laitteissa, jotka tukevat vain aiempaa standardia. Tiedosto läpäisee EPUB-validoinnin (epubcheck) ilman virheitä, mikä on vaatimus useimpien vähittäiskauppaplataformien lähettämiseen ja vahva rakenteellisen oikeellisuuden indikaattori.

Kirjailijoille, joilla on useita kirjoja tai useita painoksia, API-kutsu voidaan integroida automatisoidun julkaisu putkeen. Markdown-käsikirjoitus on tallennettu versiohallintaan (Git, esimerkiksi), metatiedot on tallennettu konfiguraatiotiedostoon ja build-komentosarja lähettää molemmat API:lle, kun uutta versiota pitää luoda. Tämä automatisoitu putkilinja tarkoittaa, että korjaukset, päivitykset ja uudet painokset voidaan tuottaa ja jakaa minuutteissa manuaalisten muotoilu-työnkulkujen tarvitsemien tuntien tai päivien sijasta. Kirjoitusvirhe-korjaus kestää kolmekymmentä sekuntia: muokkaa Markdown, suorita build-komentosarja, lataa uusi EPUB vähittäiskauppaplataformille.

API-kutsun yksinkertaisuus piilottaa sen taustalla olevien operaatioiden monimutkaisuuden. API jäsentää Markdown, luo XHTML-sisällön tiedostoja jokaiselle luvulle, luo OPF-manifestin ja selkän, luo NCX:n ja Navigation Document:n, upottaa ja viittaa kannen kuvaan, jäsentää kaikki metatiedot Dublin Core:n ja EPUB-standardien mukaan, paketoi kaiken EPUB-kontaineriformaattiin (joka on todellisuudessa erityisesti rakennettu ZIP-tiedosto) ja validoi tuloksen EPUB-spesifikaatiota vastaan. Kaikki nämä operaatiot, joista jokainen edustaa mahdollista epäonnistumisen pistettä manuaalisessa EPUB-tuotannossa, käsitellään automaattisesti ja luotettavasti joka kerta.