Over at The DevOps Collective and PowerShell.org, we’ve been keeping our free ebooks in PenFlip. Thing is, PenFlip sucks. Great idea, but deeply broken, and the author appears to have vanished. Meh, it was free. But moving there was, on paper, the right idea: it’s a Git-based repository where you write in Markdown, and it publishes to a variety of friendly formats on-demand. But… broken.
I looked at both GitBook and LeanPub as alternatives. They’re similar. GitBook is Git-based and entirely for free, open-source books. LeanPub is a sort of “agile publishing” platform where you can give books away or sell them. Both start with Markdown source, and both publish to PDF, MOBI, and EPUB. LeanPub lets you give books away for free but “suggest” a selling price, and lets the reader ultimately select their price, if they want to pay for it. But they require registration and sign-in, which not everyone loves. GitBook has a great online HTML-based reader, and lets you link to individual chapters, which can be useful. But its PDF rendering is less fun, especially for code rendering (and I haven’t found a plugin to better the situation). So in a test for Creating HTML Reports in PowerShell, our readers were pretty much split 50/50. Tipping the scales slightly was the fact that some readers couldn’t access GitBook from work, due to some proxy blocking activity. Weird.
But… both services give you the option of storing your manuscript in GitHub. They accept webhook “pings” from GitHub when you do a push, so they know to pull your manuscript and re-generate their copy. So I wondered if I couldn’t publish to both, and just let readers choose which one they preferred. Hmm.
Turns out, you can. LeanPub was especially responsive and helpful. No, make that proactive, because when I’d borked my book and effectively blanked out the pages, they emailed me and explained my problem. So what follows is a guide to getting this to work.
GitBook offers a very handy native desktop editor, which can be configured to push to your GitHub repo rather than their own Git repo, and I love working with it. So I wanted that to work as part of all of this.
You will need a unique repository in GitHub for each book. You cannot group books in subfolders of a single repo.
You will need the following files and folders:
- /manuscript – this subfolder is needed for LeanPub; all of your chapter files, in Markdown format, go here
- /manuscript/images – LeanPub needs this, too, and you should store any images here
- /manuscript/images/title_page.png (or .jpg) – book cover for LeanPub
- /cover.jpg – book cover for GitBook
- /book.json – this is a GitBook configuration file, and if you don’t have it, it’s OK
- /README.md – this is used by GitBook to display a blurb about your book on its web page
- /SUMMARY.md and /manuscript/book.txt – these are your tables of contents
Table of Contents
The LeanPub book.txt is the easy one; they also support a sample.txt if you want to provide a free sample of your book. This is just a list of chapter files, which are expected to be in /manuscript:
introduction.md html_report_basics.md gathering_the_information.md building_the_html.md combining_html_reports_and_a_gui_application.md contacting_me.md
The GitHub SUMMARY.md is a bulleted list of links. This lets you link to your chapter files:
# Summary * [ReadMe](README.md) * [Introduction](manuscript/introduction.md) * [HTML Report Basics](manuscript/html_report_basics.md) * [Gathering the Information](manuscript/gathering_the_information.md) * [Building the HTML](manuscript/building_the_html.md) * [Combining HTML Reports and a GUI Application](manuscript/combining_html_reports_and_a_gui_application.md) * [Contacting Me](manuscript/contacting_me.md)
Only a little more complicated.
Keep your images, if you need any, in /manuscript/images. It’s just easier. Image references then look like this:
Both GitBook and LeanPub will thus be OK with them.
Although LeanPub lets you upload covers through their GUI, don’t. Doing so turns off the ability to keep the cover in your source code. Both services have recommendations for cover size, and I’ve indicated in the bullet list above where they go.
Setting Up LeanPub
LeanPub, which has amazing service (did I mention that?) has a great tutorial on configuring their service to pull from GitHub. If you set up a new book and specify that it’s coming from GitHub, their GUI will walk you through everything, and will ask you for your repo address and whatnot. You’ll need to add the LeanPub service on the GitHub repo options, and that’s what tells GitHub to ping LeanPub when you push in new content.
You’ll still have to set up most of the book metadata, like pricing, description, short description, and so on, through their GUI.
But here’s the catch: LeanPub doesn’t use a true GitHub webook. Instead, they use the older service architecture. That enables them to send more information than GitHub does in a webhook, but it means you’re stuck with what that service does. And what it does is generate a new preview for your book. It does not publish that revision, a process which also can entail emailing your book’s purchasers to let them know a new version is available. And that’s probably a good thing, given the email notification feature. So you still have to go into their GUI and manually click “Publish New Version” to send that preview into production. You could possibly automate this, as LeanPub does expose a REST API, through something like IFTTT, but I haven’t probed that far.
Setting Up GitBook
GitBook has published part 1 of a 3-step process to making them work with GitHub. The other two parts aren’t actually too bad. Linking (step 2) can be done in the GitBook Editor – you just point it to your GitHub repo for the book, instead of its default GitBook repo URL. For Step 3, add a push webhook, in JSON format, like this:
And yes, you have to get GitBook to generate that for you. While doing the Permissions thing (Step 1, which they’ve published), GitBook offered to create my webhook. It says it failed, but in fact it didn’t – and it displayed the correct webhook URL regardless, so I could have done it manually if I’d needed to.
I’ll update this as we progress through converting additional ebooks over to the new platforms, but the above should pretty much be all the tricky bits.