Markdown na EPUB ze Spisu Treści, Rozdziałami i Okładką w Jednym Wywołaniu API

Branża wydawnicza przez dziesięciolecia budowała zawiłe łańcuchy narzędzi do produkcji książek. Rękopisy przenosiły się od procesorów tekstu przez oprogramowanie do układu stron do generatorów PDF na pliki gotowe do druku za pośrednictwem potoku, który obejmował wielu specjalistów i wiele licencji oprogramowania na każdym etapie. Kiedy pojawiły się e-booki, potok zyskał dodatkową złożoność zamiast uproszczenia: ten sam rękopis musiał teraz wytwarzać zarówno gotowe do druku pliki PDF, jak i reflowable EPUB, formaty z fundamentalnie różnymi filozofiami dotyczącymi sposobu prezentacji treści. Format druku blokuje wszystko na miejscu. Format e-książki pozwala wszystkiemu płynąć. Wytwarzanie obu ze źródła jest problemem, który tradycyjny łańcuch wydawniczy obsługuje całą elegancją łatanki.

Pisarze, którzy sami publikują, stają w obliczu tej złożoności łańcucha bez instytucjonalnego wsparcia, jakie zapewniają tradycyjni wydawcy. Rękopis istnieje jako dokument Word lub Google Doc. Konwersja na prawidłowo sformatowany EPUB wymaga nauki specjalistycznego oprogramowania do produkcji e-książek (Calibre, Sigil, Vellum) lub opłacenia formatora, który pobiera opłatę za projekt. Krok formatowania, który nie dodaje żadnej kreatywnej wartości do książki, staje się wąskim gardłem między ukończeniem rękopisu a udostępnieniem go czytelnikom. Dla autorów publikujących wiele książek kumulatywne koszty i czas tego kroku formatowania są znaczące i całkowicie przewidywalne, co czyni go idealnym kandydatem do automatyzacji.

Ebooks API redukuje cały proces konwersji do jednego wywołania API. Napisz książkę w Markdown, który jest formatem, który każdy edytor tekstu może wytworzyć i który każdy pisarz może nauczyć się w dziesięć minut. Wyślij zawartość Markdown razem z metadanymi i opcjonalną okładką. Otrzymaj profesjonalny plik EPUB ze strukturalnym spisem treści, prawidłowo wyznaczonymi rozdziałami, osadzoną okładką i wszystkimi metadanymi wymaganymi przez sprzedawców e-książek i biblioteki. Jedno wejście, jedno wywołanie, jedno wyjście. Cały łańcuch wydawniczy skompresowany do żądania HTTP.

Dlaczego Markdown jest idealnym formatem do pisania książek

Przydatność Markdown do pisania książek nie jest natychmiast oczywista dla pisarzy przyzwyczajonych do edytorów tekstu sformatowanego. Format wygląda prosto, niemal prymitywnie, w porównaniu ze sformatowanym widokiem w Word lub Google Docs. Ale ta pozorna prostota jest dokładnie jej siłą do pisania długoformatowego. Markdown całkowicie oddziela zawartość od prezentacji, co oznacza, że pisarz skupia się na tym, co mówi, bez rozpraszania się lub ograniczenia tym, jak będzie wyglądać. Decyzje dotyczące prezentacji podejmuje się później podczas procesu konwersji, gdzie mogą być stosowane konsekwentnie i zmieniane całkowicie bez dotykania rękopisu.

Nagłówki rozdziałów w Markdown są zaznaczane symbolami hash. Jeden hash wskazuje tytuł książki. Podwójne hashe wskazują tytuły rozdziałów. Potrójne hashe wskazują nagłówki sekcji w rozdziałach. Ta hierarchiczna struktura bezpośrednio mapuje się do struktury nawigacji EPUB: tytuły rozdziałów stają się wpisami spisu treści, nagłówki sekcji stają się podwpisami, a tytuł książki staje się elementem nawigacji najwyższego poziomu. Pisarz tworzy strukturę książki poprzez proste oznaczenie nagłówków, a API automatycznie tłumaczy tę strukturę na framework nawigacyjny EPUB.

Akapity są oddzielone pustymi liniami. Nacisk jest zaznaczany asteryskami. Cytaty blokowe są zaznaczane kątkami. Linki są zaznaczane nawiasami kwadratowymi i nawiasami. Każda z tych konwencji Markdown ma bezpośredni odpowiednik w wewnętrznym HTML EPUB, a konwersja jest deterministyczna: to samo wejście Markdown zawsze daje tę samą strukturę EPUB. Ta przewidywalność jest ważna dla autorów, którzy publikują poprawki lub zaktualizowane wydania, ponieważ zmiany w Markdown powodują odpowiednio precyzyjne zmiany w EPUB bez wprowadzania skutków ubocznych formatowania.

Przenośność plików Markdown to kolejna znacząca zaleta. Rękopis napisany w Markdown to zwykły plik tekstowy, który można otworzyć, edytować i kontrolować wersję za pomocą dowolnego narzędzia na dowolnym systemie operacyjnym. Nie jest powiązany z konkretną wersją procesora tekstu, nie wymaga konkretnej licencji oprogramowania do dostępu i nie pogarsza się w czasie, gdy formaty oprogramowania ewoluują. Rękopis Markdown napisany dzisiaj będzie czytelny w dokładnie tej samej postaci za dziesięć lub dwadzieścia lat, co nie można powiedzieć o żadnym zastrzeżonym formacie dokumentu. Dla autorów, którzy planują utrzymywać i aktualizować swoje dzieła przez długi okres, ta trwałość formatu jest znaczącą zaletą.

Metadane i co czyni EPUB profesjonalnym

Profesjonalny plik EPUB zawiera więcej niż tylko zawartość książki. Zawiera metadane, które opisują książkę do systemów, które ją rozpowszechniają, katalogują i wyświetlają. Tytuł, autor, wydawca, język, data publikacji, ISBN, opis i kategorie przedmiotów są wszystkie osadzone w pliku EPUB jako strukturalne metadane, które sprzedawcy e-książek, systemy biblioteczne i aplikacje do czytania używają do prawidłowego katalogowania i wyświetlania książki.

API przyjmuje te metadane obok zawartości Markdown i osadza je w EPUB zgodnie ze specyfikacją OPF (Open Packaging Format), która definiuje, jak powinny być strukturowane metadane EPUB. Metadane nie są po prostu wklejane do nagłówka pliku; są formatowane zgodnie ze standardami metadanych Dublin Core, które używa EPUB, z odpowiednimi typami elementów, atrybutami i deklaracjami przestrzeni nazw, których oczekują narzędzia sprawdzające i platformy sprzedażowe. EPUB z prawidłowo strukturowanymi metadanymi jest akceptowany przez Amazon KDP, Apple Books, Kobo, Google Play Books i każdą inną główną platformę handlową bez żadnych zmian.

Obraz okładki jest szczególnie ważnym elementem metadanych, ponieważ jest pierwszą rzeczą, którą potencjalny czytelnik widzi w każdym środowisku handlowym. API przyjmuje plik obrazu okładki (JPEG lub PNG) i osadza go w EPUB z odpowiednimi wpisami manifestu, odnośnikami grzbietowymi i deklaracjami metadanych, które powodują, że aplikacje czytające wyświetlają go jako okładkę książki. Obraz jest również zmieniony i zoptymalizowany w razie potrzeby, aby spełnić wymagania dotyczące wymiarów i rozmiaru pliku, które nakładają platformy handlowe, zapewniając, że EPUB jest gotowy do sprzedaży bez ręcznego przetwarzania obrazów.

Osadzanie ISBN zasługuje na szczególną wzmiankę, ponieważ jest to identyfikator, który łączy książkę z globalną infrastrukturą handlu książkami. EPUB z prawidłowo osadzonym ISBN można katalogować w bibliotekach, śledzić przez sprzedawców, odwoływać się na stronach recenzji i jednoznacznie identyfikować w każdym kontekście, w którym dyskutuje się o książkach lub je sprzedaje. API osadza ISBN w metadanych EPUB przy użyciu formatu określonego przez Międzynarodową Agencję ISBN, zapewniając kompatybilność z systemami, które używają ISBN do identyfikacji i zarządzania katalogiem.

Spis treści i struktura rozdziału

Spis treści w EPUB pełni dwie funkcje, które różnią się od spisu treści w drukowanej książce. W drukowanej książce spis treści to strona, która wymienia tytuły rozdziałów i numery stron. W EPUB spis treści to element nawigacji, który umożliwia bezpośrednie przejście do dowolnego rozdziału lub sekcji i jest wyświetlany przez interfejs nawigacji aplikacji czytającej, a nie jako wyrenderowana strona. Dobrze ustrukturyzowany spis treści EPUB czyni książkę nawigowalne w taki sam sposób, w jaki dobrze ustrukturyzowana strona internetowa jest nawigowalna: czytelnicy mogą przeskoczyć bezpośrednio do dowolnego rozdziału bez przeszukiwania całej książki sekwencyjnie.

API generuje spis treści ze struktury nagłówków w zawartości Markdown. Każdy nagłówek poziomu drugiego (podwójny hash) staje się wpisem rozdziału w spisie treści. Każdy nagłówek poziomu trzeciego (potrójny hash) staje się wpisu podrzędnym pod jego rozdziałem nadrzędnym. Ta dwupoziomowa struktura nawigacji zapewnia wystarczającą szczegółowość dla większości książek bez przytłaczania interfejsu nawigacji nadmierną liczbą wpisów podrzędnych. Spis treści jest generowany zarówno jako element nawigacyjny (NCX dla kompatybilności EPUB2 i Navigation Document dla EPUB3), zapewniając, że książka działa prawidłowo w starszych czytnikach e-booków i nowoczesnych aplikacjach do czytania.

Przerwania rozdziałów w wygenerowanym EPUB odpowiadają nagłówkom poziomu drugiego w Markdown. Każdy rozdział zaczyna się na nowej stronie w czytelniku e-booków, co zapewnia wizualne oddzielenie rozdziałów, które oczekują czytelnicy. API wstawia odpowiednie podziały stron XHTML i wpisy grzbietowe, aby zapewnić, że czytniki e-booków traktują każdy rozdział jako odrębną jednostkę nawigacyjną, a nie jako ciągłe przewijanie. To oddzielenie rozdziałów umożliwia również czytelnikom e-booków wyświetlanie tytułów rozdziałów w wskaźniku postępu czytania, pokazując czytelnikowi, który rozdział aktualnie czyta i jak daleko w nim się zaawansował.

W przypadku książek o złożonych strukturach, takich jak części zawierające wiele rozdziałów, dodatkami lub sekcjami materiałów wstępnych, hierarchia nagłówków Markdown naturalnie dostosowuje się do tych struktur. Nagłówki poziomu pierwszego mogą oznaczać części, nagłówki poziomu drugiego oznaczają rozdziały w częściach, a nagłówki poziomu trzeciego oznaczają sekcje w rozdziałach. API mapuje tę hierarchię do struktury nawigacji EPUB wiernie, tworząc spis treści, który odzwierciedla logikę organizacyjną książki niezależnie od tego, ile poziomów zagnieżdżenia używa autor.

Jedno wywołanie i jak wygląda żądanie API

Wywołanie API, które generuje EPUB, to żądanie POST zawierające zawartość Markdown, pola metadanych i opcjonalnie plik obrazu okładki. Zawartość Markdown to treść książki, zaznaczona nagłówkami, akapitami i innymi elementami Markdown, które używa autor. Pola metadanych to pary klucz-wartość: tytuł, autor, język, opis, ISBN, data publikacji i wszelkie dodatkowe pola Dublin Core, które chce uwzględnić autor. Obraz okładki, jeśli zostanie dostarczony, jest wysyłany jako załącznik pliku.

Odpowiedź to sam plik EPUB, gotowy do pobrania, dystrybucji lub wysłania na platformę handlową. Plik jest zgodny ze specyfikacją EPUB 3 ze zmianami wstecz kompatybilności EPUB 2, co zapewnia, że działa na każdym nowoczesnym czytelniku e-booków i aplikacji do czytania, a także na starszych urządzeniach, które obsługują tylko wcześniejszy standard. Plik przechodzi walidację EPUB (epubcheck) bez błędów, co jest wymagane do przesłania na większość platform handlowych i silnym wskaźnikiem poprawności strukturalnej.

Dla autorów z wieloma książkami lub wieloma wydaniami, wywołanie API można zintegrować z zautomatyzowanym potokiem publikacji. Rękopis Markdown jest przechowywany w kontroli wersji (Git, na przykład), metadane są przechowywane w pliku konfiguracyjnym, a skrypt budowania wysyła oba do API za każdym razem, gdy trzeba wygenerować nową wersję. Ten zautomatyzowany potok oznacza, że poprawki, aktualizacje i nowe wydania mogą być tworzone i rozpowszechniane w minutach, a nie w godzinach lub dniach, które wymagają ręczne potoki formatowania. Naprawa literówki zajmuje trzydzieści sekund: edytuj Markdown, uruchom skrypt budowania, prześlij nowy EPUB na platformę handlową.

Prostota wywołania API skrywa złożoność operacji, które się za nim kryją. API analizuje Markdown, generuje pliki zawartości XHTML dla każdego rozdziału, tworzy manifest i grzbiet OPF, generuje NCX i Navigation Document, osadza i odwołuje się do obrazu okładki, strukturuje wszystkie metadane zgodnie z normami Dublin Core i EPUB, pakuje wszystko do formatu kontenera EPUB (który jest faktycznie specjalnie ustrukturyzowanym plikiem ZIP) i weryfikuje wynik względem specyfikacji EPUB. Wszystkie te operacje, z których każda stanowi potencjalny punkt awarii w ręcznej produkcji EPUB, są obsługiwane automatycznie i niezawodnie za każdym razem.