Sunday 6 April 2014

Workflow to create a new LeanPub book from blogger posts

After creating a number of Leanpub based books, I've come up with a workflow that works quite well for me.

This workflow is based on Managing LeanPub book's Markdown content using Git and GitHub (synced to back to LeanPub via DropBox) which is supported by the following technologies:

  • Markdown: for content creation 
  • Git: for version control and distributed authoring 
  • GitHub: for managing issues and community contributions (via Pull Requests) 
  • DropBox: to sync data with LeanPub (from a local git repo) 
  • LeanPub: used to create eBook versions (pdf,mobi, epub), sell book via dedicated web page and provide a management website for authors to manage the entire publishing+sale process.
Here are the step-by-step instructions on how to create a book from a number of my blogger posts (in this case my FluentSharp related blogs).

Step 1) create the LeanPub book

Login into LeanPub, and open the Book's page from the main user's dashboard, and click on the Create Another Leanpub Book Now! button:

In the New Book page, enter the title of your book and the book's URL (I usually use _ in the title so that it looks better in the browser's location bar)

After clicking on the Create Book button, you will have a brand new Leanpub book (pre-populated with some sample content)

Step 2) Sync with DropBox

Once the book is created my first step is to enable DropBox support.

This is done in the Writing Settings page: 

... where we need to click on the Sync with Dropbox checkbox and the Switch to File Mode button

... after a couple seconds Leanpub will send an dropbox invitation to the email provided:

... which looks like this in DropBox

Once the invitation is accepted:

... a dropbox folder will exist with the contents on the current book

Step 3) Change book formatting

Next I open the Book Formatting page:

... and click on the Custom button:

... and make the following changes:

  • enable Page breaks after every section
  • disable Show links as footnotes in PDFs
  • set Font Size to 11pt
  • set Page Size to US Letter

  • use a sans-serif font (see why at Serif vs. Sans: the final battle)
  • use Parts, Chapters and Sections in the Table of contents (with dots)
  • use Number Parts, chapters and sections (for the Section Numbering)

Finally, click on Update Theme to save changes

Step 4) Import posts from blogger

This is the only section that has a bit of scripting required.

That is due to the fact that I don't want to import all of my blogger posts (more than 1000 by now), I only want the posts with a specific label, in this case the FluentSharp posts:

To export just these posts I wrote an Groovy script (see this gist) that I execute using the Eclipse Groovy REPL plugin:

The only value I change is the categoryFilter variable (which in this case is set to FluentSharp). Also note below the value of the exportXmlFile which is where we will find the Leanpub-ready export file (the blog-04-06-2014.xml file was created via blogger export function, and contains ALL posts)

Another nice feature of this script is how it shows a preview (in a on-the-fly-created-Eclipse-view) of the posts exported (including the title, publish data, categories/labels and content)

Here is the Posts_with_Only_FluentSharp.xml file created by the script

Back in Leanpub, I go to the Import action page:

... scroll down into the Import from a Blogger Export section, use the Chose File to select the Posts_with_Only_FluentSharp.xml file:

... and finally click on Start Import button:

This will take a while, but when in the 7/28 Publish changes to Dropbox... step of the Leanpub import workflow:

... we can actually see the new files pop-in into Dropbox's manuscript folder:

... and images folder:

Step 5) Sync with GitHub

The next step is to create a GitHub repository for this book.

In this case I used the repo:

... which was created with a default and LICENSE file.

NOTE: The 'git commands' shown below need to be executed on a computer/vm that is synced with Dropbox, and has a local copy of the (Leanpub created) Practical_FluentSharp folder.

a) open a terminal in the local Dropbox folder for the Practical_FluentSharp book:

b) create a local repository, clone the GitHub repo and commit the local files:
  • $ git init 
  • $ git remote add origin
  • $ git pull origin master
  • $ cp ../Practical_AngularJS/.gitignore .
  • $ git add -A
  • $ git commit -m 'First commit of converted files'  

For reference, here are the contents of the .gitignore file (required so that Leanpub's preview and published files are not committed to the git repository):
.DS_Store .dropbox Icon? preview published
c) push the local commit to GitHub:
  • $ git status
  • $ git push origin master

The GitHub repo now looks like this:

Step 6) set a GitHub Webhook to trigger the Leanpub sample creation

A really useful workflow is to trigger the Leanpub sample creation every time there is a git commit.

As the Leanpub's preview page nicely explains

We can have a create Subset.txt file (in this case edited directly via GitHub) containing a couple chapters (ie filenames) which will be used to create a partial preview of the book.

The way it works is by using the Leanpub API:

... and the GitHub's Webhooks capabilities (available on the settings page of the target repository)

The Webhook payload URL for this book (that triggered Leanpub's book preview generation) looks like this{APIKEY} and is used here:

GitHub provides a really nice interface to see these Webhooks in action. For example here is the one we just created:

To see the Webhook in action (i.e being triggered on commit), I executed the following Git commands:
  • git pull origin master

...followed by:
  • $ git status
  • $ git add -A
  • $ git commit -m 'updating some images'
  • $ git push origin master

After the push (with new commit), refreshing the GitHub's Webhooks page shows that there was a new delivery:

... and a quick look at Leanpub's Preview page shows that there is an Preview workflow process in place:

After about a minute the (local and remote Dropbox) preview folder of this book is updated with the updated pdf:

Containing the chapters selected in the Subset.txt file