LeanPub provides an easy and efficient way to create and publish your own books. While Amazon and its friends allow self-publishing, I was not quite taken to MS Word to write technical books. The whole flow of inserting images, code with special formats, and even changing the heading etc. took a lot of time.

Writing books in Microsoft Word is a pain.

LeanPub offered a more seamless way. It allows you to create books through two distinct options –

  1. Write content in text files (and upload to Dropbox, GitHub or BitBucket)
  2. Write content in the Markua markdown editor on LeanPub through a browser It also helped that I would take the 80% royalty offered by LeanPub in the free plan (as compared to 70% in Amazon). The writing process itself was ok –
  • Markua editor in LeanPub is not a quite delightful user experience (opinion)Writing in plain text files were not really intuitive – at first. But became much easier after a few iterations.
  • I had no issues in following Markua, a different dialect of the markup. But I was not quite happy that it was not widely accepted in the larger world as-is
  • However, once the writing was done, you click on a few buttons to write introductions, choose images and you are all set to publish the book on LeanPub platform.  

The Problem

I had a problem with LeanPub in the middle of my first technical book. My book had a good number of screenshots, blurbs and code samples. The process became more iterative in the beginning, but after 30-60 min one would get the hang of it (documentation helps).

Experiments with many markdown elements made me run the preview tool to know how the final book turns up. I did not know that was a problem until I came to this screen –

leanpub preview - max number reached

“You have reached max number of previews and publishes this month”, the app cheerfully declared. Normally this is not an issue. The only problem – I had tried embedding code files within files, and I had no idea how they work and whether I was right in doing so. The best thing to do at this time was to soldier on with the book and worry about this whole problem later. That time would probably reset my monthly limits and everyone will be happy. Not me. I had to explore the whole markdown ecosystem, critique the various editors, and know for myself on how to become unstuck to Markua.  

Exploring Alternatives

First things first: Markua can be easily understood by other markdown editors. It has its quirks, but most things work (at least worked for me) until you use some things that are not common – like embedding code from other files.

The first option was to use something that could make sense of Markua locally. I could find three ways to do that-

While the first two were not considered, I was in for a disappointment with Leanpub converter. The PIP installed fine but was broken (probably with the newer versions of Pandoc). I tried to look at the code –  I am no Python expert and I was approaching my deadlines really fast.
The quickest thing to do was to write a utility on my own or go all manual! I did what other sensible developers would do – go manual.

Other Markdowns to the Rescue

I tried running Pandoc on the files for the problem at hand. It worked well, but images do not turn up.

Other utilities expect the full path of the image, while Markua expects in the relative path.
For e.g., Image in markua:
In other editors –
Markua makes assumptions on ‘resources’ folder.

Following were the differences that I needed to iron out-

  • Correct image paths
  • Embedded files (e.g. code samples ) need to change. I simply brought the embedded content back.
  • Strange differences with a bulleted and numbered list that I could not replicate everywhere
  • I also recognized that if I go this route, I may break the functionality in LeanPub. I had to choose of the two and I chose to opt-out.

The logical option was to try out alternatives to write Markdown, and figure out the PDF generation separately.

  • I tried Texts2, which kept complaining that its friend Pandoc 2 was not installed. I was using it in the neighbouring window and refused to believe the program.
  • Tried a couple of online editors – but the process of getting stuff out of my PC and getting that back in was tedious
  • I tried Markdown2 Editor. The preview did not work.
markdown2 editor crash

Typora it is

It was then I remembered Typora. I had discovered Typora by accident a good 2-3 months before the above incident, but my feeble brain could not quite remember that.

  • A beautiful looking app that just works
  • Typora opens all text/MD documents in a folder, and I can easily work with them instead of multiple windows
  • Markdown preview is instant. Infact, you can happily write like any “normal” editor if you choose
  • Has themes!I used Typora and some external utilities to change text and do a quick review-
  • Go to File | Preferences and select the option to “Use Relative paths where possible” for images
  • Find and replace “(images” to “(resources/images” across all files (use a program like FAR)
  • Prefix/suffix embedded files with “TODO-” – search and replace markdown tags like “<<” After ironing out the differences, a couple of potential improvements were noted for my flow in Typora.
  • Write flowcharts and sequence diagrams in Typora itself rather than in an external program
  • Merge the pages – the different files did not matter since Typora had a good outline system
  • Use consistent image paths. This can improve the flow since my default screenshot software ShareX copies the full path of images (or can copy entire image to the clipboard that can be pasted directly in Typora)
  • I upload code to GitHub and reference that in the book. Instead, I could upload the code to a Gist and embed that! For e.g.
<h1>I am Groot</h1>
  <h2>I am Groot</h2>

Now my book writing flow is completely local and changed to-

  • Create markdown in Typora
  • Export to PDF (check ePub version if I have nothing else to do)
  • Preview by feeding PDF to Kindle Create Of course, Typora isn’t perfect. For e.g. the preview screen is distracting with all the animation magic, images do not have titles, and people have complained about markdown not being correct all the time. However, I found it works well with the given constraints.  

Other Reasons that Impacted my Decision

Although I had an immediate problem to solve with the preview, there were other things giving me second thoughts on Leanupub –

  1. LeanPub platform allows a DRM free distribution of PDF. Although I knowingly got in with that knowledge, I was quite taken aback by the distribution of a preview version of my book to tens of people. I was beginning to wonder the revenue aspect of releasing a PDF to the wild. Yes, books on other platforms are also pirated but that takes longer than a simple email of a document.
  2. The default theme in the free version is satisfactory. A paid-version with $8 / month is not an option for a few reasons.

I have the utmost respect for what LeanPub is doing, but that platform is not for me at this time.