[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 Dropbox or GitHub writing modes, where you manage plain text files and images in a manuscript folder on your computer. If you are writing in our In-Browser writing mode, please go here.

If you just set up a book for the first time in GitHub, you may not need to read any of this! Just check to see that you have pointed Leanpub to the correct repository, and you have successfully added Leanpub as a collaborator on the repository, and you have set up the manuscript folder correctly in the repository. You can view instructions for all of this, with links to detailed, step-by-step walkthroughs of the process, on the Getting Started page for your book here:

leanpub.com/YOUR_BOOK/getting_started 

tl;dr Skip down to the section called Approach #1 (recommended)

When book generation failure happens, sometimes it can be really easy to resolve, but sometimes it can be hard and take time.

In this article, we recommend you start with the assumption that the best thing to do is to assume the problem will be easy to find and fix, and choose the quickest approach to a solution, given that assumption.

If the quick approach doesn't work, then we have also set out more comprehensive approaches below.

Please note that because most Leanpub authors who encounter book generation failure are programmers (currently, anyway), this article will mostly take a programmer-style approach to debugging a book.

If you're not a programmer and you have trouble following along, that's our fault; please let us know where we could improve this article by telling us where we lost you.

Approach #1 (recommended): Compare the most recent version of your manuscript that worked, with the first version of your manuscript that failed, and make guesses about what might be causing the problem. This way you can evaluate a minimum number of changes between a working manuscript and a failing manuscript, and probably spot the problem pretty quickly,

Approach #2: Do a binary search on your current, failing manuscript. Basically, this involves deleting half the file names in Book.txt, and running a preview to see if if fails. You repeat the process of deleting file names in Book.txt until you've narrowed down a single file that is causing the problem. Then, you do the same thing in the file that is causing the problem, deleting half of its contents, and running previews until you find the source of the problem, in the contents of the file.

Approach #3: Compare the latest version of your manuscript that worked, with the first version of your manuscript that failed, and evaluate the differences systemically (instead of guessing like you do in Approach #1). In most cases this will be slower than guessing, but if guessing doesn't work, you may need to fall back on this approach, or one of the other approaches.

Approach #4: Compare your current, failing manuscript, to the most recent version of your manuscript that worked, and evaluate the differences systemically (instead of guessing like you do in Approach #1). This approach is typically more "noisy" than Approach #1 or Approach #3, because the deviation between the two manuscript folders is presumably greater. This is the slowest and in most cases the most time-wasting approach to debugging a book, but it is perhaps the most comprehensive approach, and allows you in a single process to see if there is more than one type of problem that is causing your book generation to fail (though that is extremely rare, which is why we recommend the other approaches, above this one).

Step 1. Make a backup copy of your book folder and store it somewhere safe on your computer.
​
Step 2. Try running a preview again to double-check that book generation is failing.

Step 3. If book generation fails, you should check to see if the problem is us, not you. 

Sometimes the reason book generation 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 folder.

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. 

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.

If you're using Git, commit everything before doing these next steps, so you can easily revert  them (not reset  them, since you are pushing afterward).

Step 4. In your manuscript folder, rename Book.txt to Book-original.txt

Step 5. In your manuscript folder, create a new file called Empty.txt 

Step 6. Open the new Empty.txt file and paste this in at the top:

Step 7. In your manuscript folder, create a new file called Book.txt

Step 8. Open the new Book.txt file and paste this in at the top:

Make sure to save all these changes, and if you're using GitHub, be sure to add the new files, and commit and push as well. (We won't keep repeating this instruction, but please remember to keep doing this!)

Now you're ready to test. Go to your book's preview page, and try creating a new preview. 

If book generation succeeds, that means you have confirmed that the problem is with something in your manuscript. Please skip ahead to Step 10 below.

Step 9. If book generation fails, that means the problem is on the Leanpub side of things, not with your manuscript.

At this stage we recommend you check the following, to see if you can spot something that might be causing the book generation failure:

[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:

...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.]

If you find anything that might be causing the problem, please change it and try running a new preview.

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 undo the changes we did earlier. If you know how to use Git, revert  the changes that way. Otherwise, do this:

You should now be ready to keep working on 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 you can't find anything you think might be causing the issue, there may be a bug in Leanpub. 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.)

Step 10. OK, now that we have confirmed that the problem is in your manuscript, it's time to compare the most recent version of your manuscript that worked, with the first version of your manuscript that failed, and make guesses about what might be causing the problem. 

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 here:

(To find the Manuscript Versions page for your book, make sure to replace YOUR_BOOK with your book's unique "slug".)

On the Manuscript Versions page, you will see a record of your actions, like this:

First, let's download the most recent version of your manuscript that worked. To do this, click the blue "create archive" link next to the latest version that shows a Result of success:

When the process completes, you will see an ugly page that looks 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.

Once you've completed the download, unzip the folder and check to see that it contains a folder called manuscript.

Next, rename this manuscript folder to last-known-good-manuscript 

Now we need to get the first version of your manuscript that failed. To do this, click the blue link to go back to the Manuscript Versions page, and click the blue "create archive" link next to the latest version that shows a Result of failure:

Repeat the process to download this manuscript.

Once you've completed the download, unzip the file and rename the manuscript folder to first-known-bad-manuscript.

If you are a programmer, you can now use diff -r to see all the differences between the folder last-known-good-manuscript and the folder first-known-bad-manuscript.

If you are not a programmer, you can also just eyeball the two folders. For example, do you see any new files in first-known-bad-manuscript that you do not see in last-known-good-manuscript? If so, then the problem might be in one of those new files.

When you spot a difference, you can now guess what the source of the problem is, and test to see if you're right.

Here's a real-world example of something an author did, that caused their book generation to fail: 

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.

If you see any "funny business" like this going on in first-known-bad-manuscript, that might be the source of the problem.

To test any differences like this between first-known-bad-manuscript and last-known-good-manuscript that you think might be causing the problem, copy the difference into that Empty.txt file you made in your current book folder in Step 9 above, and try running a new preview on each difference, until you get book generation to fail.

Step 11. Now that you've found the source of the problem, you need to fix it everywhere it appears in your files. Hopefully you've caught the error early, and you only need to fix it in the one place where you just found it.

For the real-world example above, here is what we did to fix the issue (adding a blank line in the middle, above where the list starts):

[Pro Tip: Often you will find that blank lines, placed before and after things you are trying, are your friend!]

Step 12. Now that you've made your fixes, let's undo the changes we did to your book folder earlier, and run a new preview.

You should now be ready to keep working on 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 you can't find anything you think might be causing the issue, there may be a bug in Leanpub. 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.)

[The rest of this article is TBD - eds.]