[This article is a work in progress! We hope it is helpful in the meantime, and welcome any feedback you might have - 2020/03/17]
Please note that these instructions are meant for authors working in our In-Browser Editor. If you are working in our Dropbox or GitHub writing modes, where you manage plain text files and images in a manuscript folder on your computer, please go here.
***
Normally Leanpub's book generators have no problem generating books, but they do run into issues from time to time. In these cases, you might see a message or get an email informing you that book generation has failed.
We've written this article to help get your book back in working order, hopefully as quickly as possible!
Section 1. Compare the version of your manuscript that most recently generated successfully, with the version of your manuscript that most recently failed to generate
The first step you should do to resolve book generation failure, is to compare the current version of your manuscript, which is failing to generate, with the latest version of your manuscript, that generated successfully. That should give you a clue as to the source of the issue, and a means to find it.
Every time you try to preview or publish a new version of your book, we try to save a version of your manuscript on the Manuscript Versions page, which you can find here:
https://leanpub.com/YOUR_BOOK/versions
...making sure to replace YOUR_BOOK with your book's unique "slug".
On the Manuscript Versions page, you will see a record of your actions. Find the latest version of your book that has a result of "success" and click the blue link that says "create archive".
Click the blue "create archive" link and you will be take to an ugly page that shows you something like this:
Click the blue link that says "download". This will give you a .zip file containing a copy of your manuscript folder, just as it was at the time of the last successful book generation result.
Rename this manuscript folder to manuscript_success.
Next, repeat this process, but use it to download the latest version of your manuscript where the result was "failure".
Once you've downloaded the new folder and unzipped it, rename the manuscript folder inside to manuscript_failure.
Now, you can compare the two manuscripts.
If you are a programmer, you can use diff -r to see all the differences between the folders in detail.
If you are not a programmer or you just don't want to compare the contents of the folder that way, open up the two folders side by side on your computer.
Look for any differences between the two folders. This may give you a clue regarding the source of the issue.
Section 2. Before moving on, test to see if Leanpub is the problem
Sometimes the reason the book generation process fails is because of something on the Leanpub side of things, rather than because of something to do with the contents of your book's manuscript.
This would typically be caused by something you did on Leanpub that is going to be included in the book. For example, if your Suggested Tweet has something in it that our book generators don't support, that could blow up the generation of your book.
[Pro Tip: To find a list of all the pages where you can work on your book on Leanpub, go to the Overview page for your book here:
https://leanpub.com/YOUR_BOOK/overview
...making sure to replace YOUR_BOOK with your book's unique "slug". Check the "Social Media" page link to find out where your Suggested Tweet it set.]
The cover image can also cause problems with book generation, since it is included at the beginning of your book.
Here are the steps you can take, to quickly test and see if something on the Leanpub side of things is the problem here:
1. Delete all the files you have in our In-Browser Editor (you have already downloaded a backup, so you're safe!). You can delete files by clicking the gear wheel and then the red "Delete" button. (Here is an article that includes a section on how to delete files, and a link to a video that you might find helpful, if you haven't seen it already.)
You won't be able to delete the last file. When you have one file left, please go to the next step.
2. Click on the remaining file, and delete all of its contents. Then, paste this content into the file:
# Chapter One
Foo
3. Rename the file to Empty.txt.
4. Try creating a preview. You can find the preview page for your Leanpub book here:
https://leanpub.com/YOUR_BOOK/preview
...making sure to replace YOUR_BOOK with your book's unique "slug".
If book generation succeeds, that means you know the problem is with something in your manuscript. Please skip ahead to section 3.
If book generation fails, we recommend you check the following, to see if you can spot something that might be causing the book generation failure:
Have you included emojis or unusual characters in your book's title or subtitle, or in your Suggested Tweet, if you have set one up?
If you have uploaded a new cover image since your last successful book generation, then you should try uploading a new book cover, noting the recommendations we give you on the Upload Book Cover page.
If you find anything that might be causing the problem, please change it and try running a new preview.
If you can't find anything on Leanpub that might be causing the problem, please go to the next section of this article.
If you do find the cause of the issue on Leanpub and resolve it, all you need to do to get your book back up and running is to add back your files and content. Here are the steps to do this:
1. Open the manuscript_failure folder and open the first file in your book.
2. Copy the contents of the file, and paste them into the Empty.txt file in our In-Browser Editor.
3. Rename Empty.txt to the original file name.
4. In the In-Browser editor, create a new file, give it the name of the second file in your book, and copy into that new file you've created in the In-Browser text editor, the contents from the relevant file in the manuscript_failure folder.
5. Repeat this process until you have added back all your files.
6. Try creating a new preview. If this succeeds, hooray! You can go back to writing your book.
(At this point, we optionally recommend that you share what you've just found on the Authors Forum. Click "New Topic" and call it something like "Book generation failure caused by [whatever you've found the cause of the issue to be]". That way, other authors can hopefully avoid having to discover this issue all over again, and we can think about how to improve our book generators and our documentation.)
If your attempt to create a preview fails, it looks like you still have an issue to resolve, this time with your the contents of your manuscript. Please proceed to the next section.
Section 3. Replace your current manuscript with the files from the last working version of your manuscript folder, and create a working preview
Before we figure out the cause of the issue, let's start by getting your book back up and generating successfully.
To do this, we'll add back the files from the manuscript_success folder.
1. Open the manuscript_success folder and open the first file in your book.
2. Copy the contents of the file, and paste them into the Empty.txt file in our In-Browser Editor.
3. Rename Empty.txt to the original file name.
4. In the In-Browser editor, create a new file, give it the name of the second file in your book, and copy into that new file you've created in the In-Browser text editor, the contents from the relevant file in the manuscript_failure folder.
5. Repeat this process until you have added back all your files.
6. Try creating a new preview. If this succeeds, hooray! Please go to the next section.
If book generation fails, that means there may be a bug in Leanpub (since the same manuscript did work in the past). In this case, please read the last section of our handy Author Support Guidelines, and then contact Leanpub author support at hello@leanpub.com, and wait for a response from us. (We typically offer support on weekdays during normal working hours, Pacific time.)
Section 5. Add content back to your book piece-by-piece, generating new previews, until you reproduce the book generation failure
Next, you are going to start adding content from manuscript_failure to the your book in the In-Browser Editor.
You will want to do this piece by piece. How big the pieces are is up to you; it will depend on how many differences there are between manuscript_success and manuscript_failure.
For example, at this stage, if you see a file in manuscript_failure that you do not see in manuscript_success, add that file to your book in the In-Browser Editor.
Next, try to create a new preview. If it works, add another file from manuscript_failure to manuscript_success, that you do not already see in your book in the In-Browser Editor, and try creating a preview again.
Repeat this process until book generation fails, when you try to create a preview.
Now you know that the problem is in the contents of the last file that you added to your book in the In-Browser Editor In this section, we will refer to this file a "breaking file" (Don't rename this file though! Just leave the actual file's name unchanged. We're only calling it a "breaking file" for the sake of brevity in these instructions)
Authors familiar with programming probably know what's coming next: you're going to do a binary search on the breaking file.
You don't need to be a programmer to do this! Here's how we're going to find the source of the book generation failure:
1. In the manuscript_failure folder, create a copy of the breaking file. Add the word copy to the name of the new file
2. Open the copy file and copy the first half of the contents of that file
3. Open the last file you added to the In-Browser text editor, and paste in the content you just got from the copy file
4. Try creating a new preview. If it succeeds, keep adding content in pieces from the copy file
6. Once book generation fails, you know the problem is in the content you just pasted into the breaking file
7. Delete half of the last piece of content that you pasted in to the In-Browser Editor.
8. Repeat this process until book generation succeeds. Then you know the problem is in the last piece of text you deleted
We hope we've provided you with enough information about this process, that at this point, you can continue this process until you have isolated the source of the problem in the contents of your breaking file.
Section 6. What to do when you have found the source of the problem
This will differ on a case-by-case basis. Here is an example, slightly modified, from a real-world case of something an author was doing, that caused book generation failure:
_DEVICE_
: \\
* 2.08 Observer pattern shareware API asynchronous
* 2.09 kernel scalable flexbox homebrew
The issue here is that things like * are used in defined cases within our markup syntax. Starting a line in Markua with an asterisk, for example, indicates a bulleted list item. Colons are also used in Markua. So, using a colon, and some backslashes, on a line before a list, was in this case confusing our book generators.
As a solution in this case, here's what we suggested (adding a blank line in the middle, above where the list starts):
_DEVICE_
: \\
* 2.08 Observer pattern shareware API asynchronous
* 2.09 kernel scalable flexbox homebrew
[Pro Tip: Often you will find that blank lines, placed before and after things you are trying, are your friend!]
Once you've found a solution and your book is generating successfully, do the following:
1, Add all the remaining content from in manuscript_failure that you do not see in the In-Browser Editor, into the In-Browser Editor.
2. Try to create a new preview. If it succeeds, hooray! You can go back to working on your book. If it fails, go to the next step.
3. Check your files for other examples of the issue you found before, and fix them all. The next time you create a preview, if it succeeds, hooray! If it fails, that means you have another problem, and you need to repeat this process, which should hopefully be a lot quicker the second time.
Finally, we optionally recommend that you share what you've just found on the Authors Forum. Click "New Topic" and call it something like "Book generation failure caused by [whatever you've found the cause of the issue to be]". That way, other authors can hopefully avoid having to discover this issue all over again, and we can think about how to improve our book generators and our documentation.)
***
Thank you for your patience! If you have any recommendations for how we can improve this article, we'd really love to hear from you.