Self-publishing: Jak napisałem książkę w markdownie?

Self-publishing: Jak napisałem książkę w markdownie?

Wciąż dopytujecie się o proces self-publishing mojej książki „TypeScript na poważnie” od strony technicznej. W czym ją pisałem? Jak tworzyłem e-booki? Dlaczego zdecydowałem się na markdown? Jakich narzędzi używałem? Śpieszę odpowiedzieć – to wszystko w tym wpisie 🙂

Przedsprzedaż książki zakończyła się ogromnym sukcesem! Teraz poświęcam całą energię na realizację złożonych zamówień. Sklep powróci 1. listopada. Jeśli chcesz, mogę Ci o tym przypomnieć – wystarczy, że zostawisz swojego maila poniżej.


Dlaczego Markdown do self-publishing?

Zdecydowałem się napisać „TypeScript na poważnie” w markdownie. Jest to prosty język, w którym używa się symboli do formatowania tekstu. Wygląda to tak, jak widać na poniższym screenshocie; zresztą w markdownie piszę też teraz niniejszy artykuł 🙂

Fragment tego artykułu w Markdownie.

Dlaczego Markdown, a nie zwykły Word, albo, w drugą stronę, znany w środowisku naukowym LaTeX? Od tego ostatniego nie udało mi się zupełnie uciec, o czym za moment, ale powodów do używania markdowna jest kilka.

Jeśli zastanawiasz się, dlaczego w ogóle napisałem książkę, to na pewno zaciekawi Cię ten wpis:

Napisałem książkę! Kilka słów o „TypeScript na poważnie”

Przede wszystkim Markdown jest niesamowicie prosty. Tekst wygląda bardzo czytelnie nawet dla laików i jest łatwy w edytowaniu z każdego urządzenia – część poprawek wprowadzałem na iPadzie i nawet na iPhonie!

Drugi powód jest nieco bardziej techniczny: Markdown wspaniale się sprawdza, jako format pośredni pomiędzy zwykłym tekstem a wieloma formatami docelowymi. Na podstawie markdowna z łatwością wygenerowałem pliki PDF, EPUB, MOBI, DOCX i HTML!

Edytor do self-publishing

Moim ukochanym edytorem jest iA Writer, w którym piszę też wszystkie blogposty. To właśnie w nim powstała cała książka! Jest to bardzo prosty edytor tekstu z podstawowym wyświetlaniem formatowania markdowna – minimalizm.

Pandoc

Sercem całej operacji jest Pandoc, czyli „uniwersalny konwerter dokumentów”, jak głosi jego strona internetowa. Użyłem tego niesamowitego narzędzia, aby na podstawie rozdziałów książki napisanych w markdownie wygenerować pliki w różnych formatach, o czym wspominałem kilka akapitów wyżej.

Nie obyło się też bez otwarcia kilku issues i nawet jednego pull requesta do Pandoc, a dodam, że jest napisany w Haskellu, więc było to nie lada zadanie!

Ogromną zaletą Pandoc jest mnogość opcji konfiguracyjnych, wtyczek do markdowna, własnych filtrów oraz świetne wsparcie dla projektów takich jak moja książka w self-publishing. Przykładowo, dopisałem własny filtr dodający nową składnię do Markdowna w celu oznaczania fragmentów tekstu, które miały nie mieć indentacji albo powinny przylegać do prawej strony.

Docker i GitHub

Do budowania książki użyłem też Dockera. Po co? Znowu dwa powody: nie chciałem zaśmiecać sobie komputera i planowałem e-booki generować automatycznie na serwerze CI. Ah, no tak, bo o tym nie wspomniałem: całą książkę trzymam oczywiście na GitHubie!

Widok repozytorium na GitHubie.

Ostatecznie więc proces wyglądał tak: Po napisaniu fragmentu tekstu robiłem git commitgit push do prywatnego repozytorium na GitHubie. Wcześniej skonfigurowałem akcję w GitHub Actions, która reagowała na zmiany w książce i automatycznie budowała obraz Dockera, a następnie używała w nim Pandoc do zbudowania książki w dwóch formatach: PDF i EPUB. Kolejnym krokiem było wygenerowanie pliku MOBI (Kindle), do czego użyłem narzędzia ebook-convert z aplikacji Calibre. Na koniec, moja akcja tworzyła nowy tag oraz release na GitHubie i dodawała do niego trzy stworzone pliki.

Self-publishing w każdym tego słowa znaczeniu!

Dostosowywanie

Większość opcji pomiędzy formatami była taka sama, ale oczywiście Pandoc umożliwia zmodyfikowanie osobno PDF i osobno EPUB, co też uczyniłem.

Wspominałem, że nie udało mi się uciec od LaTeXu, bo ostatecznie zmuszony byłem dopisać kilkadziesiąt linii kodu w LaTeX doprowadzających mojego PDF-a do takiego efektu, jakiego pożądałem. Pandoc do generowania plików PDF zamienia Markdown na Latex i dopiero później na PDF – i uwierz mi, mimo, że brzmi to niepotrzebnie skomplikowanie, to fantastyczna opcja, która umożliwiła mi praktycznie dowolne zmienianie wynikowego pliku!

EPUB to połączenie XHTML i CSS i tutaj również Pandoc pozwala na jego modyfikowanie. Do e-booków dołączyłem własny plik CSS oraz fonty w formacie .otf – dokładnie tak samo, jak na stronach internetowych. Co ciekawe, w EPUB działają media queries, a więc można sposób formatowania e-booka uzależnić choćby od wielkości ekranu, na którym plik został otwarty! Przykładowo, w przypadku „TypeScript na poważnie”, na urządzeniach z ekranem mniejszym niż 600px tekst nie będzie wyjustowany (bo wtedy źle wyglądał), a wyrazy na końcu wierszy nie będą dzielone.

Dodatkowo, Pandoc umożliwia zapisywanie różnych metadanych do różnych formatów plików. Dzięki temu mogłem z łatwością podać inne numery ISBN dla EPUB i PDF. ISBN dla formatu MOBI (Kindle) dodałem narzędziem ebook-convert.

Skrypty

Nie byłbym Programistą®, gdybym nie poświęcił kilku godzin na napisanie skryptów, które automatyzowały coś, co zrobiłbym ręcznie w godzinę 😜

Mówiąc poważnie, zależało mi na kilku rzeczach:

  1. Aby każdy żaden przykład kodu w książce nie zawierał błędów składniowych,
  2. Aby każdy fragment był jednakowo sformatowany,
  3. Aby spis treści poprawnie działał na urządzeniach Apple.

Formatowanie kodu

Wszystkie te problemy rozwiązałem poprzez stworzenie skryptu napisanego w (no nie zgadniecie) TypeScripcie. Do rozwiązania dwóch pierwszych problemów użyłem narzędzia Prettier. Skrypt wyszukiwał w tekście książki fragmentów kodu, następnie formatował je Prettierem i zapisywał. Miałem dość restrykcyjne ustawienia, szczególnie pod względem długości wersów:

{
  "printWidth": 53,
  "tabWidth": 2,
  "proseWrap": "preserve",
  "trailingComma": "all",
  "arrowParens": "always",
  "endOfLine": "lf"
}

53 znaki fontem o stałej szerokości to była maksymalna liczba, jaką mogła pomieścić jedna linijka w książce drukowanej i PDF.

Fragment skryptu do formatowania kodu w książce.

To załatwiło większość problemów, ale nie wszystkie – niektóre linijki nadal były dłuższe niż wyznaczony limit znaków, ale takie sytuacje mój skrypt również wykrywał i informował o tym, abym ręcznie poprawił. Dodatkowo, niektóre z fragmentów kodu sformatowałem ostatecznie samodzielnie, aby były bardziej czytelne.

Spis treści

Ku mojemu wielkiemu zaskoczeniu, okazało się, że narzędzia Apple mają problem z polskimi znakami w linkach do rozdziałów. Ponieważ Pandoc generował odnośniki automatycznie i zawierał w nich po prostu pełne tytuły rozdziałów, dla urządzeń Apple stanowiło to problem nie do pokonania!

Napisałem więc kolejny skrypt, który polskie znaki w odnośnikach zamieniał na odpowiedniki w alfabecie łacińskim („ą” na „a”, „ź” na „z” i tak dalej). Uff.

Efekt finalny self-publishing

Jakie są efekty tego mojego self-publishing? Każdy, kto kupił e-booka widzi 🙂

Jeśli masz jakieś pytania odnośnie self-publishing, procesu powstawania książki, technikaliów – to zostaw komentarz, albo napisz do mnie! Odpowiadam każdemu.

Nie wysyłamy spamu, tylko wartościowe informacje. W każdej chwili możesz się wypisać klikając „wypisz się” w stopce maila.

Subscribe
Powiadom o
guest
5 komentarzy
Most Voted
Newest Oldest
Inline Feedbacks
View all comments
Jakub
24 dni temu

Super sprawa, powinieneś to jakoś opublikować na otwartej licencji. Oczywiście usuwając treść książki i wstawiając lorem ipsum.

Piotr
Piotr
23 dni temu

Artykuły do bloga też trzymasz w GIT?

Piotr
Piotr
21 dni temu

Rezygnujesz z WP?