Writing technical books in MS Word is a pain.LeanPub offered a more seamless way. It allows you to create books through two distinct options –
- Write content in text files (and upload to Dropbox, GitHub or BitBucket)
- Write content in the Markua markdown editor on LeanPub through a browser
- 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
The ProblemIn the middle of my first technical book, I had a problem with LeanPub. 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 – “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 AlternativesFirst 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-
- https://github.com/panozzaj/local-leanpub – quite old. Last commit five years back
- https://github.com/eviltester/pandocifier – could not play around with Java. Looks like a one-off project for the author
- https://github.com/hayd/leanpub – looked promising
While the first two were not considered, I was in for 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.
Image in markua:
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 bulleted and numbered list that I could not replicate everywhere
- I tried Markdown2 Editor. The preview did not work.
- 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
Typora it isIt 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!
- 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 “<<“
- 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!
- Create markdown in Typora
- Export to PDF (check ePub version if I have nothing else to do)
- Preview by feeding PDF to Kindle Create
Other Reasons that Impacted my DecisionAlthough I had an immediate problem to solve with the preview, there were other things giving me second thoughts on Leanupub –
- 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.
- The default theme in the free version is satisfactory. Paid version with $8 / month is not an option for a few reasons.