Thank you for visiting this eBook design tutorial. We now have an eBook design startup—BB eBooks—dedicated to helping independent authors and small presses get their eBooks formatted, converted, and ready for sale at all the major online retailers (e.g. Amazon's Kindle Store, Barnes & Noble's Nook, iBookstore, Smashwords, etc.) Please contact us for a no-obligation quote. For those writers, editors, and publishers looking to go the DIY route for eBook production (you probably are if you visited this page), we offer free online tutorials and apps to help you professionally design your eBook. Please visit our Developers page and let’s work together to improve the overall standards of eBooks. Also, please sign up for the mailing list for promotions, design & marketing tips, plus eBook industry news.
The full tutorials for the eBook formatting series include a basic XHTML tutorial, a tutorial for converting your manuscript into XHTML, and a Calibre tutorial for converting XHTML into eBooks. For those looking for something more advanced, you can also peruse the Regular Expressions tutorial, as well as the EPUB and KindleGen tutorial. Templates for XHTML and EPUB are also available for your formatting arsenal. Additionally, there are some helpful hints for formatting for Smashwords in this tutorial.
Table of Contents for Calibre Tutorial
Introduction to Calibre
Adding XHTML Source Code to Calibre
Adding Metadata
Converting XHTML into EPUB and MOBI Formats
An Overview of Conversion Options
Creating your EPUB eBook
Verifying Your EPUB eBook
EPUB Verification Checklist
Troubleshooting EPUB
Verifying Your EPUB
Creating your MOBI eBook
Verifying Your MOBI Format
MOBI Verification Checklist
Troubleshooting MOBI
Verifying MOBI
Video Tutorial
Introduction to Calibre
Calibre (pronounced "Caliber") is an eBook library management system that is open source. It has powerful and efficient conversion tools to change one eBook format into another format. The process of converting XHTML into EPUB and MOBI formats is relatively easy without requiring extensive programming knowledge on the part of the average self-publisher. Calibre was developed by a gentleman named Kovid Goyal, who is very active on the MobileRead forums. Therefore, new updates are constantly being issued to address changing requirements and standards as the large eBook distributors and eReaders evolve over time. This guide uses version 0.8.13 of Calibre; however, you should use the most updated version.The purpose of this tutorial is to convert your XHTML source code into perfect EPUB and MOBI eBook formats, which can then be uploaded to the Amazon.com Kindle Store and Barnes & Noble NOOK.
Adding XHTML Source Code to Calibre
The first step toward converting your eBooks is to add your XHTML source code into the Calibre program, so that you can convert your code into the desired EPUB and MOBI formats.Perform the following steps:
- Open the Calibre program
- Click "Add books"
- Add your XHTML file
![]() |
Adding XHTML Source Code to Calibre (Step 2) |
Adding Metadata
You are now going to add all of the metadata to your XHTML (e.g. the eBook's author, title, description, etc.) This metadata will be embedded in your EPUB and MOBI formats after you complete conversion. While you will have to enter similar data when you upload your eBook to the Amazon.com Kindle Store and Barnes & Noble NOOK, these eBook retailers will hopefully one day decide to recognize this metadata entered in Calibre.The Metadata screen in Calibre is pretty self-explanatory, but here is a step-by-step explanation:
- Verify your record is selected in the content management screen (#1)
- Click "Edit metadata"
- Enter the title of your eBook under "Title" (note: this will be loaded in Calibre with the text you defined in between the <title> tags in your XHTML, but you can change it inside Calibre)
- Enter the title of your eBook under "Title Sort" (this is how it will be alphabetically sorted, so "The Poop that Took a Pee" could be sorted under "Poop that Took a Pee, The", if desired)
- Enter the name of the author under "Author"
- Enter the name of the author under "Author Sort" (e.g. it could be "Paul Salvette" or "Salvette, Paul")
- If the eBook is a series, enter the name under "Series" and the series number under "Number"
- Add an eBook cover by clicking the "Browse" button (600x800 JPEG strongly recommended by this guide)
- Give yourself a "Rating" of 5 stars if you are awesome or 1 star if you are an ironic hipster
- Enter the meta tags that describe the eBook under "Tags" and separate with commas (e.g. "fiction, crime, thriller, mystery")
- If your eBook has an ISBN, enter it under "Ids", otherwise leave blank
- Add the day's date under "Date"
- Add the month and year under "Published"
- Add your own name under "Publisher" if you are indie or your company if you are a small press
- Enter your back-jacket description under "Comments"
- Click "Ok" to save
![]() |
Adding Metadata in Calibre |
Converting XHTML into EPUB and MOBI Formats
Calibre offers an extensive amount of options for the conversion of eBooks. Some of them are useful if you are converting from older formats (like .lit or .pdb), but this guide will examine the options used to convert XHTML into EPUB and MOBI.An Overview of Conversion Options
The Calibre Manual discusses every option in detail, but this guide will examine the basic options that are needed to properly convert XHTML into EPUB and MOBI formats.Now that you have entered all the metadata for your eBook perform the following steps:
- Click on "Convert Books" in the Calibre menu
![]() |
Convert Books Button on Calibre |
Metadata: N/A - you should alter your Metadata per the method above
Look and Feel:
- You can adjust the line spacing in between each line of text in your eBook (the default of 120% is good, and you can set to 240% if you want double-spaced).
- You can adjust the justification of the text. Setting to "Justified" will force your text vertically aligned on both the left and right, except when you defined a "text-align: value;" style in your XHTML.
- Leave everything else as the default
![]() |
Look & Feel Options |
Page Setup:
- Input Profile should be left as "Default Input Profile"
- Output Profile should be left as "Generic e-ink"
- For the margins, you can adjust the values to add spacing between the text and the edge of the eReader. For EPUB, the default 5.0pt on the left, right, top, and bottom is okay. However, the MOBI format can be set to 0.0pt, since the Kindle eReader automatically has some spacing between the text and the edge of the screen. Please note that 72.0pt correlates to 1 inch.
![]() |
Page Setup Options in Calibre |
- For "Detect Chapters at (XPath expression):", there is a default XPath expression that tries to determine where chapters are located in order to insert page breaks. Since your XHTML code has the page breaks already inserted, this feature is unnecessary. Make this box blank.
- For "Chapter mark:", it should be set to "none". This is because you are not relying on Calibre to detect chapters or use their algorithms to determine where page breaks should be located.
- The "Remove Fake Margins" feature tries to find left and right margins that are embedded into the XHTML code in individual paragraphs. This feature is useful when you are converting from older eBook formats that have screwy source code, but for your purposes, you should uncheck it.
- The "Insert page breaks before (XPath expression):" is a way to automatically insert page breaks during the conversion. Since you have specified exactly where you want your page breaks in the XHTML source code, this feature is not necessary. You should make this box blank.
![]() |
Structure Detection Options |
- If checked, the "Force use of the auto-generated Table of Contents" generates a new NCX Table of Contents. This is necessary, because you have not created an NCX yet. This box should be checked.
- The "Do not add detected chapters to the Table of Contents" should be checked, because you do not need Calibre to determine the chapter structure of your eBook. The NCX Table of Contents will be compiled based on your <div id=> tags.
- The "Number of links to add to Table of Contents" field specifies the max number of links that will be added to the NCX. If you set to "0", then there will be no limit.
- The "Level 1 TOC (XPath expression):" determines how Calibre will determine each link for the NCX Table of Contents. Based on the fact that you coded <div id="anchorname"> for each desired point on your NCX, you can use the XPath expression "//h:div[@id]". This basically tells Calibre to look for any <div> tag with an id= attribute and use that in NCX Table of Contents. You can click on the magic wand button to generate alternative XPath expressions, if necessary.
- This guide recommends not using Level 2 and Level 3 TOC (the sub-headings on the Table of Contents), since some eReading devices cannot support this feature (e.g. the Barnes & Noble NOOK).
![]() |
Table of Contents Options in Calibre |
EPUB Output:
- If output format is set to "EPUB" in the top right, then the "EPUB Outbut" button will appear on the left side bar.
- The defaults should not be adjusted, except for "Preserve Cover Aspect Ratio". Click this if you want to maintain the aspect of your cover ratio no matter the dimensions of the eReader. This is a good option to check or else you will get skewed cover images on Adobe Digital Editions.
![]() |
EPUB Output Options |
MOBI Output:
- If output format is set to "MOBI" in the top right, then the "MOBI Outbut" button will appear on the left side bar.
- Checking the "Do Not Add Table of Contents" box will make it so the "Table of Contents" view inside the Kindle returns an error message. This is the annoying HTML Table of Contents that only exists within MOBI formats and not the NCX Table of Contents. If you leave this box blank, it will add a traditional HTML Table of Contents on the last page based on your NCX compilation. If you generated your own "Table of Contents" in Section xx, then you will have two traditional HTML Tables of Contents and a NCX Table of Contents. You may want to consider using a different XHTML source code just for MOBI that doesn't have a traditional HTML Table of Contents encoded. Alternatively, you can tweak the EPUB format and convert it to MOBI in KindleGen (advanced).
- In "Title for Table of Contents", you can type the title of the traditional HTML Table of Contents for MOBI format.
- For the "Ignore Margins", if you leave this blank it will introduce some bizarre margins into the MOBI format. Headings will be unevenly spaced and there will be other annoyances. Make sure this box is checked.
![]() |
MOBI Format Options |
Creating your EPUB eBook
Now that you have a basic understanding of the Calibre conversion options, you can finally convert your XHTML source code into an eBook. This guide recommends the following settings during the conversion for EPUB:- Input Format: ZIP
- Output Format: EPUB
- Look and Feel
- Disable font size rescaling: unchecked
- Base font size: 0.0pt
- Font size key: blank
- Minimum line height: 120.0%
- Line height: 0.0pt
- Input character encoding: blank
- Remove spacing between paragraphs: unchecked
- Insert blank line between paragraphs: unchecked
- Text justification: Justify text
- Linearize tables: unchecked
- Smarten punctuation: unchecked
- Transliterate unicode characters to ASCII: unchecked
- Keep ligatures: unchecked
- Heuristic Processing
- Enable heuristic processing: unchecked
- Page Setup
- Input Profile: Default Input Profile
- Output Profile: Generic e-ink
- Margins Left: 5.0pt
- Top: 5.0pt
- Right: 5.0pt
- Bottom: 5.0pt
- Structure Detection
- Detect chapters at (XPath expression): blank
- Chapter mark: none
- Remove first image: unchecked
- Remove fake margins: unchecked
- Insert metadata as parge at start of book: unchecked
- Insert page breaks before (XPath expression): blank
- Table of Contents
- Force use of auto-generated Table of Contents: checked
- Do not add detected chapters to the Table of Contents: checked
- Allow duplicate links when creating the Table of Contents: unchecked
- Number of links to add to Table of Contents: 0
- Chapter threshold: 6
- TOC Filter: blank
- Level 1 TOC (XPath expression): //h:div[@id]
- Level 2 TOC (XPath expression): blank
- Level 3 TOC (XPath expression): blank
- EPUB Output
- Do not split on page breaks: unchecked
- No default cover: unchecked
- No SVG cover: unchecked
- Flatten EPUB file structure: unchecked
- Preserve cover aspect ratio: checked
- Split files larger than: 260KB
If you click on "Click to open" under path, it will take you to the folder where the file is. Calibre uses a complicated directory structure, and the "Click to open" button is a real timesaver.
![]() |
EPUB Conversion Complete |
Important Note: If you convert your book into an EPUB format again, it will overwrite the existing EPUB.
Verifying Your EPUB eBook
Now that you have created your EPUB, you will want to make sure the conversion produced a perfect eBook. This is the exact file that you will upload to the Barnes & Noble NOOK store for sale, and what the reader will actually be viewing on their eReader. You should check your EPUB on both Adobe Digital Editions and the NOOK for PC.To open your EPUB on NOOK for PC, perform the following steps:
- Start NOOK for PC
- Click "my library"
- Click "my stuff"
- Click "ADD NEW ITEM"
- Open your EPUB file
![]() |
Opening EPUB in NOOK for PC |
EPUB Verification Checklist
Here is a list of things you should be checking for to ensure that a proper conversion of your XHTML took place.- Verify Cover Image is the correct aspect
- Verify NCX Table of Contents has the proper text
- Click through the NCX Table of Contents to make sure it goes to the proper place
- Verify margins
- Change the font sizes and scroll through the eBook to verify text is reflowable and font size remains consistent
- Verify centered text and images is centered
- Verify special characters can be read properly
- Verify page breaks
Troubleshooting EPUB
Problem: Cover Image is skewed![]() |
Skewed Cover |
Problem: NCX has the incorrect text
![]() |
Wrong text on NCX |
Problem: Clicking on NCX Table of Contents goes to the wrong location (usually the page before the next chapter)
![]() |
NCX Targets Wrong Location |
Problem: Margins are uneven
![]() |
Improper Margins |
Problem: Text is different sizes and/or not reflowable
![]() |
Poorly Reflowable Text |
Problem: Text or images not centered properly
![]() |
Text Aligned Incorrectly |
<span style="text-align: center;">centered text</span>Not recognizing centered text is a notorious bug on the iBooks app, and using the <span> tags should help alleviate the problem. However, this guide does not use this technique as general practice, since the Smashwords will distribute a different EPUB to the iBookstore. For information on Smashwords formatting, you can visit this tutorial.
Problem: Special Characters are garbled
![]() |
Special Character Junk |
Problem: Page breaks are not properly set
![]() |
Erroneous Page Breaks |
Verifying Your EPUB
Once you are satisfied with the look and feel of your EPUB eBook in both NOOK For PC and Adobe Digital Editions, you should have the file validated. This can be easily done for free by uploading it to the Threepress Consulting website.![]() |
Winning EPUB |
If there are any problems sith the EPUB, the Threepress validotr will inform you of the errors. You can fix most of them by adjusting your XHTML source code, and then re-converting into EPUB through Calibre. The most common validation failure is not specifying alt="text description" on <img> tags.
Creating your MOBI eBook
This guide recommends the following settings during the conversion of XHTML source code into MOBI:- Input Format: ZIP
- Output Format: MOBI
- Look and Feel
- Disable font size rescaling: unchecked
- Base font size: 0.0pt
- Font size key: blank
- Minimum line height: 120.0%
- Line height: 0.0pt
- Input character encoding: blank
- Remove spacing between paragraphs: unchecked
- Insert blank line between paragraphs: unchecked
- Text justification: Justify text
- Linearize tables: unchecked
- Smarten punctuation: unchecked
- Transliterate unicode characters to ASCII: unchecked
- Keep ligatures: unchecked
- Heuristic Processing
- Enable heuristic processing: unchecked
- Page Setup
- Input Profile: Default Input Profile
- Output Profile: Generic e-ink
- Margins Left: 0.0pt
- Top: 0.0pt
- Right: 0.0pt
- Bottom: 0.0pt
- Structure Detection
- Detect chapters at (XPath expression): blank
- Chapter mark: none
- Remove first image: unchecked
- Remove fake margins: unchecked
- Insert metadata as page at start of book: unchecked
- Insert page breaks before (XPath expression): blank
- Table of Contents
- Force use of auto-generated Table of Contents: checked
- Do not add detected chapters to the Table of Contents: checked
- Allow duplicate links when creating the Table of Contents: unchecked
- Number of links to add to Table of Contents: 0
- Chapter threshold: 6
- TOC Filter: blank
- Level 1 TOC (XPath expression): //h:div[@id]
- Level 2 TOC (XPath expression): blank
- Level 3 TOC (XPath expression): blank
- MOBI Output
- Do not add Table of Contents to book: unchecked or checked (depending)
- Title for Table of Contents: Table of Contents
- Put generated Table of Contents at start of book instead of end: unchecked
- Ignore margins: checked
- Rescale images for Palm devices: unchecked
- Use author sort for author: unchecked
- Disable compression of the file contents: unchecked
- Personal Doc tag: [PDOC]
If you click on "Click to open" under path, it will take you to the folder where the MOBI file is.
![]() |
MOBI Conversion Complete |
Verifying Your MOBI Format
Now that you have created your MOBI, you will want to make sure the conversion produced a perfect eBook. This is the exact file that you will upload to the Amazon.com Kindle store for sale, and what the reader will actually be viewing on their Kindle, Kindle for PC, Kindle for iPad, etc.MOBI Verification Checklist
You should check your MOBI in the Kindle Previewer. Under the "devices" menu, you can view it as a regular Kindle, Kindle for iPad, Kindle DX, etc. You should verify your MOBI in a variety of different device emulators.Here is a list of things you should be checking for to ensure that a proper conversion of your XHTML took place into the MOBI format:
- Verify traditional HTML Table of Contents is accessible
- Verify NCX Table of Contents has the proper text
- Click through the NCX Table of Contents to make sure it goes to the proper place and Kindle navigation buttons work
- Verify margins (a big problem with MOBI)
- Change the font sizes and scroll through the eBook to verify text is reflowable and font size remains consistent
- Verify centered text and centered images
- Verify special characters can be read properly
- Verify page breaks
Troubleshooting MOBI
Problem: HTML Table of Contents Missing![]() |
Table of Contents Not Accessible |
Problem: NCX Table of Contents has incorrect text
![]() |
NCX Table of Contents with Textual Errors |
Problem: NCX Table of Contents goes to wrong location and/or Kindle navigation buttons are not working
![]() |
NCX Table of Contents Navigation Error |
The arrows on Kindle can go to the next/previous page or next/previous section. The next/previous section feature jumps through the Kindle based on next/previous entry in the NCX Table of Contents. If the NCX Table of Contents is the way you want it, the Kindle navigation features will work fine.
Problem: Margins on Kindle are erroneous
![]() |
Example of Off-center Heading on Kindle |
Formatting margins for MOBI can be particularly troublesome in Calibre. If the problem persists, look at your XHTML source code to verify that you have reset margin-left and margin-right to 0.01em in the CSS. If that doesn't work, try converting from EPUB into MOBI with KindleGen (advanced).
Problem: Font-size changes and text is poorly reflowable
![]() |
Font size changes on Kindle |
Problem: Text or images not centered properly
![]() |
Text Alignment Problems in Kindle |
Problem: Special Characters are garbled
![]() |
Special Character Issues on Kindle |
Solution: The MOBI format has much better support for special characters than EPUB. The Amazon Kindle provides guidance on what character sets it will accept, but it seems to be more versatile than the guide says. For example, Thai script (not mentioned in the Amazon Kindle Publishing guide PDF) seems to work fine on the Kindle Previewer. However, verify in your XHTML source code that you converted all special characters into the HTML Entities. Ensure that you used the HTML Entity Name codes and not the HTML Entity Number codes.
Problem: Page breaks not correct
![]() |
Erroneous Page Breaks |
Verifying MOBI
Since MOBI will only be used for uploading to the Amazon.com Kindle Store, you really only have to test it on the Kindle Previewer. It can be a challenge to get Calibre to convert into the MOBI format properly, especially in regards to margins. It may be beneficial for you to learn about the actual EPUB files by visiting the EPUB tutorial. From there, you can convert an EPUB file into MOBI using the Amazon.com KindleGen program. This is slightly more advanced than the rest of the guide, but it will give you a good understanding of the nuts and bolts of eBooks.Video Tutorial
![Share/Bookmark](http://static.addtoany.com/buttons/share_save_171_16.png)
9 comments:
he website was how do i say it… relevant, finally something that helped me. Many thanks
Absolutely great guide here, thanks. I'm not creating my own table of contents, but I have a thought on how you might work around the MOBI problem if you do. Until now I have uploaded word documents to KDP and Pubit with very good results. The reason I am switching to using xhtml is that I need the mobi file for other purposes and I didn't feel it was appropriate to use the one that Smashwords generates.
Anyhow, in order to get the kindle to link to your own toc, have you tried adding an anchor tag with the name set to "toc"? When I upload a Word document, I create a bookmark with this name and that causes the kindle menu to link to that location. When I've looked at the html that kdp generates from the Word document, I see it converts that to an anchor tag. Maybe calibre won't convert it correctly to the mobi file, I just figured it's worth a try if you haven't tried it.
Thanks, Edward. I will have to give that a try. I usually do my own EPUBs without Calibre and then convert to MOBI with Kindlegen, because it gives me more control. I will I have to try out that id="toc" feature. The MOBI has a lot of weird stuff that you just have to find out by trial and error.
Yeah, if you're going to use kindlegen anyway, then no real need to try it. I don't even know if it will work, just a thought based on what I saw on KDP uploads.
After publishing my first book via CreateSpace, I expected conversion to Kindle format to be simple and smooth sailing. I was mistaken. I learned there is no simple, easy, quick way to do this well. I then discovered your excellent, detailed instructions and learned (from you) what I needed to know to complete this process. Thank you so much for providing such an excellent resource. As one who teaches technology for a living, I appreciate and admire your superb teaching skills. Great book, too. Please know that you probably prevented a suicide, so my wife thanks you as well.
One thing I didn't notice in your writeup but figured out on my own: If I create a MOBI file from my html with Calibre, then modify the original html, and then re-convert to update the same book listing with Calibre, the html file in the Calibre-created zip file is not replaced automatically with my new html. So I copy/pasted the revised html file into the zip file each time I re-converted, and that worked fine. I suppose maybe I could have made revisions directly in the html file in Calibre's zip instead of the original html file. Any way, all is well, and thanks again.
Ron,
Glad to hear that the book was useful, and I wish you the best of luck with your eBook. Also glad no one offed themselves.
Hi Paul, been using your tutorials to prep and create an eBook and everything’s gone wonderfully with the exception of the Calibre-generated TOC. Can’t figure out why. I’d appreciate any insight you may have if you’re game and have a moment. If not, I completely understand! Here’s the deal in the event you can help:
I’m using div tags and anchors, all NCX links are renamed. After Calibre does its thing (using your Level 1 TOC XPath "//h:div[@id]"), I get the same result with both epub and mobi: my coded TOC names/links show/work perfectly and the Calibre-generated TOC links work but out of 120 links, only 9 are named correctly.
__The first two links in the Calibre-generated TOC show correctly, are images for title page (p class=title) and copyright page (p class=front).
__The 3rd link, the dedication page (p class=h1) has just two words on it, is supposed to show as “Dedication” in the TOC but instead the two words are shown.
__Links 4 through 114 are chapters 1 through 110 (p class=chapter) showing incorrectly as “1” through “110” as opposed to “Chapter 1” through “Chapter 110”.
__Links 115 through 120 (p class=h2) show correctly.
I’ve gone over and over the code in Notepad++ and see no errors or reasons as to why Calibre would take exception to the h1 and chapter classes.
Thanks,
Zan
Zan,
This tutorial is a bit out of date and I've sort of given up on Calibre. It sounds like you should learn how to make an EPUB and MOBI without Calibre. It's more professional and works better. Check out this tutorial here and good luck.
Thanks, Paul.
In all my searching for information, I began to suspect that Calibre is suited for uncomplicated projects.
At a glance, your ‘EPUB and KindleGen Tutorial’ hurts my head, but it’s been a demanding day and I’ll give it a rational look with the aid of coffee tomorrow!
All the best,
Zan
Post a Comment