DEV Community

Emily Jane
Emily Jane

Posted on Edited on

From Markdown to Amazon KDP: A Pre-Publication Checklist for Developer-Authors

In my previous post I covered how to write a book as plain Markdown, build it with Pandoc and check it in CI. That gets you a manuscript that builds on a clean machine. It does not get you a book that is ready to sell.

This follow-up covers the gap: turning your Markdown build into files a retailer will accept, checking them properly, and deciding which jobs are worth handing to someone else. I use Amazon KDP as the example because it is where many first-time authors start, but the same ideas apply to other stores. Always check each platform's current file rules, because they change.

Two Products, Two Sets of Files

An ebook and a paperback are different artifacts, even when they come from the same source.

Ebook   Paperback
Enter fullscreen mode Exit fullscreen mode

Format EPUB (reflowable) PDF (fixed layout)
Layout Reader controls font and size You control trim size, margins, page numbers
Cover One image Front, spine and back, sized to the page count
Biggest risk Structural errors, broken navigation Margins, bleed, wrong page size

Treat them as two build targets from one repository, the same way you would build a web app and a mobile app from one codebase.

Add a Stylesheet to the EPUB

Pandoc's default EPUB works, but a small stylesheet makes it look intentional. Create epub.css:

css
body {
line-height: 1.5;
margin: 0 5%;
}

h1, h2, h3 {
page-break-after: avoid;
line-height: 1.2;
}

pre, code {
font-family: monospace;
font-size: 0.85em;
}

pre {
white-space: pre-wrap; /* wrap long lines instead of overflowing */
padding: 0.6em;
background: #f4f4f4;
}

img {
max-width: 100%;
height: auto;
}

Then build with it:

bash
pandoc metadata.yaml chapters/*.md -o book.epub \
--toc --toc-depth=2 \
--css=epub.css \
--epub-cover-image=cover.jpg

The white-space: pre-wrap rule matters for technical books. Code that overflows the screen on an e-reader is one of the most common complaints about developer ebooks, so wrap it, and keep your listings short enough to read on a small screen.

Build the Paperback PDF at the Right Size

For print, set the page size and margins explicitly. This example uses a 6 × 9 inch trim size with a wider inner margin for the binding:

bash
pandoc metadata.yaml chapters/*.md -o book-print.pdf \
--pdf-engine=xelatex --toc \
-V documentclass=book \
-V classoption=twoside \
-V geometry:paperwidth=6in \
-V geometry:paperheight=9in \
-V geometry:inner=0.875in \
-V geometry:outer=0.625in \
-V geometry:top=0.75in \
-V geometry:bottom=0.75in

Two warnings:

Margins depend on page count. Print platforms set minimum inner margins that grow with the number of pages, so confirm the numbers against the current guidelines once your page count is known.
Default Pandoc styling is functional, not designed. Headers, drop caps, running titles and proper front matter usually need a custom LaTeX template or a layout specialist.
Use a Makefile So Builds Are One Command

Typing long commands invites mistakes. A small Makefile keeps both targets reproducible:

makefile
CHAPTERS := $(sort $(wildcard chapters/*.md))

.PHONY: all epub pdf check clean

all: epub pdf

epub: book.epub
pdf: book-print.pdf

book.epub: metadata.yaml epub.css cover.jpg $(CHAPTERS)
pandoc metadata.yaml $(CHAPTERS) -o $@ --toc --toc-depth=2 \
--css=epub.css --epub-cover-image=cover.jpg

book-print.pdf: metadata.yaml $(CHAPTERS)
pandoc metadata.yaml $(CHAPTERS) -o $@ --pdf-engine=xelatex --toc \
-V documentclass=book -V classoption=twoside \
-V geometry:paperwidth=6in -V geometry:paperheight=9in \
-V geometry:inner=0.875in -V geometry:outer=0.625in \
-V geometry:top=0.75in -V geometry:bottom=0.75in

check: book.epub
java -jar epubcheck.jar book.epub

clean:
rm -f book.epub book-print.pdf

Now make check builds the EPUB and validates it in one step, and your CI job can call the same target.

Check the Things a Linter Cannot See

Validation catches structure, but many problems only show up when you look at the output. Before you upload, do the following:

Open the EPUB in at least two readers. A desktop reader and a phone app often render the same file differently.
Click through the table of contents. Every entry should land on the right chapter.
Search the output for leftovers. Look for TODO, FIXME, lorem, and placeholder names.
Check every image at the smallest screen size. Screenshots that are readable in a PDF are often too small on a phone.
Print a few pages. Even a home printer shows margin and font-size problems that a screen hides.
Re-run every code sample on a clean machine, using the exact version of the language and libraries the book names.

A short script can automate part of step 3, failing the build if draft markers are still in the manuscript:

bash
if grep -rnE "TODO|FIXME|lorem ipsum" chapters/; then
echo "Draft markers found. Fix them before publishing." >&2
exit 1
fi
Metadata Is Part of the Product

Retail listings are searched. The title, subtitle, description, categories and keywords decide whether the right readers find your book. Keep this information in your repository too, for example in a listing.md file:

markdown

Listing

  • Title:
  • Subtitle:
  • Short description (one sentence):
  • Long description (150-250 words):
  • Categories (check the store's current list):
  • Keywords (7 phrases a reader might actually search):
  • Series / edition:
  • Price and territories:

Writing this down early, and committing it with your chapters, saves a scramble on launch day.

Decide What to Outsource

By now your pipeline handles drafting, building and validation. The jobs that remain are mostly human ones:

Editing and proofreading. A person who did not write the book will find unclear explanations, inconsistent terms and gaps in the logic.
Cover and interior design. A cover is judged in seconds, usually as a small thumbnail. Interior layout affects whether the book feels professional.
Publishing setup and distribution. Accounts, tax information, categories and store rules take time to learn.
Marketing. A book rarely finds readers by itself. Launch planning, reviewer outreach and an author website all take sustained effort.

You can do these yourself, hire freelancers for individual pieces, or use a service that bundles them. Miami Book Publishers is one example of the bundled kind. According to its website, it offers editing and proofreading, formatting, cover design, Amazon KDP publishing and book marketing.

Whichever route you choose, get these answers in writing before you pay anyone:

What exactly is included, and what costs extra?
Who owns the rights to the book, the cover and the interior files?
Will you receive the final source files, not only the finished book?
Who controls the retail accounts, and who receives the royalties?
What are the revision limits, the timeline and the refund terms?
Can you see samples or past work in your genre?

The website's pages did not state pricing or contract terms when I checked, so ask for them directly and compare quotes from more than one provider.

Keep the Repository as the Source of Truth

One advantage of this workflow is that you are never locked in. If an editor or designer works from your exported files, bring their changes back into the Markdown source, then rebuild. Otherwise your repository and the published book will drift apart, and your next edition becomes painful.

A simple rule helps: the Markdown in Git is the master copy, and every other file is generated from it.

Final Pre-Publication Checklist
make check passes and the EPUB validates with no errors.
The paperback PDF uses the correct trim size and margins for your page count.
No draft markers remain in the text.
Code samples were run on a clean machine with the versions stated in the book.
The cover meets the store's current size and format rules and still reads as a thumbnail.
Title, subtitle, description, categories and keywords are written and reviewed.
At least one person outside your team has read the whole draft.
You know who owns the rights, files and accounts, and you have it in writing.
A launch plan exists, even a small one: who you will tell and where.
Wrapping Up

Writing the book in Markdown solved the hardest engineering problem, which is keeping a long project maintainable. Publishing adds a different set of tasks, and most of them are easier if you treat them like releases: automate the checks, version the outputs and keep a clear record of every decision.

If you have published a technical book, what surprised you most about the process? I would like to hear which steps you automated and which ones you were glad to hand over.

Top comments (0)