I just published my first technical programming book. It's titled, React Ready: Learn modern React with TypeScript. This book will turn React beginners into skilled and confident modern React developers. React Ready covers all the React fundamentals and essentials in order to give readers a solid React foundation that they can build upon. Go from React rookie to React ready!
I started writing React Ready within VS Code. The goal was to start by creating it as an eBook. The tool that I used to create the eBook was Ibis by Mohamed Said. It's a simple PHP tool to write eBooks in markdown format. Ibis auto-generates a table of contents, provides syntax highlighting for code, adds a cover photo of your choice, and supports a light and dark theme.
I chose Ibis because it provides an easy way to compose a book with text and code snippets in markdown format. Once you're done writing your book in markdown, Ibis allows you to generate a PDF that you can sell as an eBook. Generating a PDF is as easy as running
I used cspell to run spell-checking on my markdown files. I ran spell-check using the following command from my terminal.
npx cspell content/**/*.md*
I designed the book cover image for React Ready using Photoshop. I added it to my Ibis project and re-ran
ibis build to re-generate a PDF of my book that included my new cover image.
I created a Lemon Squeezy account to sell my eBook. Lemon Squeezy is an e-commerce platform that makes it easy to sell digital products. The download links for digital products are securely signed and throttled. I decided to go with Lemon Squeezy instead of Gumroad because of Gumroad's new commission fee of 10% for each digital sale. Here's my Lemon Squeezy digital products page.
Markdown's simple way of formatting plain text made it quicker for me to structure my book, write down what I wanted to say, and add code snippets. I was able to do all this with markdown, without wasting time on the formatting issues that come with using something like Microsoft Word. Markdown allowed my ideas to keep flowing in order to complete the book.
The downside to writing a book in markdown is that you can't sell it directly on Amazon's Kindle Direct Publishing as a Kindle or paperback book. Even if Ibis generated a PDF of my book, Kindle Direct Publishing does not work well with PDF files. When creating a Kindle or paperback book with Kindle Direct Publishing, using a Word document is best.
My next challenge was figuring out how to convert my markdown files into a Word document. I came across a tool named Pandoc for this. It's easy to install and simple to use. One basic pandoc command will convert a markdown file into a Word document.
pandoc -o output.docx -f markdown -t docx filename.md
This command converts
output.docx, which is a well-formatted Word document reflecting all of the formatting used in the markdown file.
I re-ran the pandoc command for every section of the book. Each time, I copied the text from
output.docx and pasted it into the main Word document for the book.
I created two main Word documents for the book manuscript. The first Word document was for the Kindle version of the book. It can have hyperlinks and it does not require page numbers. The second Word document was for the paperback version of the book. Since it's a print version, it benefits from having page numbers. Also, a print version cannot support hyperlinks, so I replaced them by typing out the actual URLs within the text.
To design the book cover for the paperback version of my book, Kindle Direct Publishing's Print Cover Calculator provided me with a template that I used as a guide layer in Photoshop. I selected 8.5 by 11 inches as the Interior trim size. Selecting the Page-turn direction was confusing. I wasn't sure what it meant. It turns out it's actually the reading direction. For English language books, choose Left to right.
Within Word, I used the standard page size of 8.5 by 11 inches. I modified the formatting for headings, body text, and quotes to my liking. For the body text, I used the Callibri font with a font size of 11 and a line spacing of 1.5. For the code snippets, I used the Consolas font with a font size of 11 and a line spacing of 1. I indented all paragraphs and added a table of contents.
The biggest challenge with moving the book form markdown to a Word document was how to format code snippets in Word. There are a few different ways to handle the formatting of programming code in Word documents.
Use screenshots: This approach can make the code hard to read. The print quality of these screenshots is unpredictable, especially if syntax highlighting is used for the images but the book is printed in black and white.
Use objects: I initially started off using OpenDocument Text objects. However, I realized that the inserted objects cannot handle code snippets that span more than one page. I needed multi-page code snippet support, so I decided to stop using objects.
Paste the code directly: I chose this approach. I copied the code snippets from the pandoc-generated Word document. Then, in the main Word document for the book, I used black for the font color of code snippets. This removed any syntax highlighting so that the code snippets would read nicely when printed in black and white.
I hope that my book publishing process has taught you a few tips and techniques that you can use when publishing your first technical programming book.