Convert AsciiDoc to MOBI

Why Convert AsciiDoc to MOBI?

Converting AsciiDoc documents to MOBI format transforms your technical documentation and manuscripts into Kindle-ready eBooks. The MOBI format is the legacy eBook format for Amazon's Kindle ecosystem, and while Amazon has transitioned to KF8/AZW3 for newer features, MOBI files remain universally compatible with all Kindle devices and reading apps ever produced. This makes MOBI an excellent choice for maximum Kindle compatibility.

AsciiDoc was designed with book authoring as a core use case, and publishers like O'Reilly Media have used it extensively for technical book production. The format's support for document structure (chapters, sections, subsections), cross-references, footnotes, index entries, and table of contents generation maps naturally to eBook structure. Converting to MOBI preserves this hierarchy as navigable chapters with a linked table of contents that readers can use for quick navigation on their Kindle devices.

The conversion process handles the transformation from plain-text markup to binary eBook container automatically. AsciiDoc headings become chapter breaks, code blocks are formatted with monospace fonts for readability on e-ink screens, images are embedded and optimized for the target device, and metadata such as title, author, and description are included in the MOBI file's metadata record. The result is a professional eBook ready for sideloading to Kindle or distribution through Amazon's Kindle Direct Publishing (KDP) platform.

For technical authors, the AsciiDoc to MOBI pipeline is particularly valuable because it allows maintaining a single source in version-controlled AsciiDoc while producing multiple output formats. You can generate MOBI for Kindle readers, EPUB for other eReaders, PDF for print, and HTML for web -- all from the same AsciiDoc source. This single-source publishing workflow eliminates the need to maintain separate versions of your content for each distribution channel.

Key Benefits of Converting AsciiDoc to MOBI:

• Kindle Compatibility: Works on every Kindle device and app ever produced
• Portable Reading: Take technical documentation anywhere in your pocket
• Self-Publishing: Ready for Amazon KDP distribution
• Navigable Structure: Chapter-based TOC for easy reference
• Offline Access: Read documentation without internet connectivity
• Compact Files: Compressed format for efficient storage
• Single Source: Maintain one AsciiDoc source, publish to many formats

Practical Examples

Example 1: Technical Book for Kindle

Input AsciiDoc file (book.adoc):

= Python for Data Science
Jane Developer
:doctype: book
:toc:
:sectnums:

== Getting Started with Python

Python is a versatile programming language
ideal for data analysis.

=== Installing Python

[source,bash]
----
brew install python3
pip install numpy pandas
----

NOTE: Use virtual environments for
project isolation.

Output MOBI file (book.mobi):

Kindle-ready eBook containing:
- Title: Python for Data Science
- Author: Jane Developer
- Navigable Table of Contents
- Chapter 1: Getting Started with Python
  - Section 1.1: Installing Python
- Formatted code blocks (monospace)
- Note callouts preserved
- Reflowable text for any Kindle
- Compatible with Kindle Paperwhite, Oasis
- Sideload via USB or Send to Kindle

Example 2: API Documentation as eBook

Input AsciiDoc file (api-guide.adoc):

= Payment API Reference
v3.2, 2024-06-15

== Authentication

All API calls require a Bearer token.

[source,http]
----
GET /api/v3/payments HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
----

WARNING: Never expose your API key
in client-side code.

Output MOBI file (api-guide.mobi):

Portable API reference eBook:
- Readable on Kindle during commute
- Authentication section with code samples
- Warning boxes rendered as styled blocks
- Quick navigation between endpoints
- Searchable on Kindle devices
- Version 3.2 metadata embedded
- Perfect for offline API reference
- Fits in pocket on any Kindle device

Example 3: Training Manual for Kindle Distribution

Input AsciiDoc file (training.adoc):

= Employee Onboarding Guide
HR Department
:icons: font

== Welcome to the Company

We're glad to have you on board!

=== First Week Checklist

. Complete HR paperwork
. Set up workstation
. Meet your team
. Review security policies

IMPORTANT: All employees must complete
security training within 30 days.

Output MOBI file (training.mobi):

Distributable training eBook:
- Send to employees' Kindle devices
- Navigable chapter structure
- Numbered checklist preserved
- Important notices highlighted
- Read on phone via Kindle app
- No printing required
- Always accessible offline
- Professional formatting maintained

Frequently Asked Questions (FAQ)

Q: What is MOBI format?

A: MOBI (Mobipocket) is an eBook format originally created by Mobipocket SA and acquired by Amazon in 2005. It is the legacy eBook format for the Kindle ecosystem, based on the Open eBook standard with PalmDOC compression. While Amazon now uses KF8/AZW3 for newer features, MOBI remains compatible with all Kindle devices and apps.

Q: Can I read MOBI files on non-Kindle devices?

A: Yes. While MOBI is primarily associated with Kindle, you can read MOBI files on many other applications: Calibre (Windows/Mac/Linux), FBReader (Android/desktop), Moon+ Reader (Android), Sumatra PDF (Windows), and Stanza. You can also convert MOBI to EPUB for use on Kobo, Nook, and other eReaders.

Q: Should I use MOBI or AZW3 for Kindle?

A: For maximum compatibility with older Kindle devices, use MOBI. For better formatting and modern features (CSS support, enhanced typography), use AZW3/KF8. Amazon's Send to Kindle service now recommends EPUB, which it converts internally. For self-publishing on KDP, you can upload EPUB and Amazon handles the conversion.

Q: Will code blocks be readable on Kindle?

A: Code blocks are preserved in monospace font in the MOBI output and are generally readable. However, long lines may wrap on smaller Kindle screens. For best results, keep code lines under 60 characters when possible. Kindle's font size adjustment helps readers find a comfortable viewing size.

Q: How do I sideload the MOBI file to my Kindle?

A: You can sideload MOBI files via USB (connect Kindle, copy to Documents folder) or use Amazon's Send to Kindle service (email the file to your Kindle email address). The Send to Kindle desktop app and browser extension also work. Note that Amazon's Send to Kindle now prefers EPUB format over MOBI.

Q: Are images preserved in the MOBI conversion?

A: Yes. Images referenced in your AsciiDoc document are embedded in the MOBI file. MOBI supports JPEG and GIF images. Large images are automatically resized for optimal display on Kindle screens. For best results, use images that are at least 600 pixels wide and in JPEG format.

Q: Can I publish the MOBI file on Amazon KDP?

A: Amazon Kindle Direct Publishing (KDP) accepts MOBI files for upload, though they now recommend EPUB format. The conversion from AsciiDoc produces a well-structured MOBI file with metadata, table of contents, and chapter navigation that meets KDP requirements. Add a cover image for professional appearance.

Q: Is the table of contents navigable on Kindle?

A: Yes. AsciiDoc's heading structure is converted to a navigable table of contents (NCX) in the MOBI file. Kindle devices display this as a clickable TOC accessible from the menu, allowing readers to jump between chapters and sections instantly. The :toc: attribute in AsciiDoc ensures TOC generation.