mobi

README

Go MOBI

This package implements facilities to create KF8-formatted MOBI and AZW3 books. We also export the raw PalmDB writer and various PalmDoc, MOBI and KF8 components as subpackages, which can be used to implement other formats that build on these standards.

Known issues

• Chapters are supported but subchapters are not
• Old readers without KF8 are not supported (Kindle 1, 2 and DX)
• Books without any text content are always malformed
• Errors during template expansion result in a panic

References

• MobileRead Wiki
  • MOBI format
  • PDB format
  • KF8 format
• Calibre source code for MOBI support
• Vladimir Konovalov's Golang MOBI writer
• Library of Congress on the MOBI format

Huge thanks to the authors of these resources.

License

MIT © Leo Gaskin 2020-2023

Documentation

Overview

Package mobi implements writing KF8-style formatted MOBI and AZW3 books.

Index

• Variables
• type Book
  • func (m Book) GetThumbFilename() string
  • func (m *Book) OverrideTemplate(tpl template.Template) Book
  • func (m Book) Realize() pdb.Database
• type Chapter
• type Chunk
  • func Chunks(strings ...string) []Chunk
• Bugs

Examples

• Book

Variables

var SupportedLocales []language.Tag

SupportedLocales is a list of locales supported by MOBI, intended for use with Go language matching facilities.

BUG(leotaku): While the MOBI language format supports regions, this implementation does not and explicitly removes region information from the locale stored in the generated MOBI file.

Types

type Book

type Book struct {
	Title         string
	Authors       []string
	Contributors  []string
	Publisher     string
	Subject       string
	CreatedDate   time.Time
	PublishedDate time.Time
	DocType       string
	Language      language.Tag
	FixedLayout   bool
	RightToLeft   bool
	Chapters      []Chapter
	CSSFlows      []string
	Images        []image.Image
	CoverImage    image.Image
	ThumbImage    image.Image
	UniqueID      uint32
	// contains filtered or unexported fields
}

Book represents all the information necessary to generate a KF8-style formatted MOBI or AZW3 book.

You are expected to initialize the Book struct using the required variables and/or builder pattern, then convert the resulting structure into a PalmDB database. This database can then be written out to any io.Writer.

Example

package main

import (
	"math/rand"
	"os"
	"time"

	"github.com/leotaku/mobi"
	"golang.org/x/text/language"
)

func main() {
	// Create simple book with chapter
	ch := mobi.Chapter{
		Title:  "Chapter 1",
		Chunks: mobi.Chunks(`Lorem ipsum dolor sit amet, consetetur sadipscing elitr.`),
	}
	mb := mobi.Book{
		Title:       "De vita Caesarum librus",
		Authors:     []string{"Sueton"},
		CreatedDate: time.Now(),
		Language:    language.Italian,
		Chapters:    []mobi.Chapter{ch},
		UniqueID:    rand.Uint32(),
	}

	// Convert book to PalmDB database
	db := mb.Realize()

	// Write database to file
	f, _ := os.Create("test.azw3")
	defer f.Close()
	err := db.Write(f)
	if err != nil {
		panic(err)
	}
}

func (Book) GetThumbFilename

func (m Book) GetThumbFilename() string

GetThumbFilename returns the filename a JPEG image in the Kindle thumbnails folder would need to have in order to be correctly associated with the generated book.

Newer Kindle readers no longer respect the thumbnail embedded in the Palm database but instead try to download the cover art from Amazon's servers using the embedded ASIN identification string. However, we can still get covers for sideloaded books by embedding a fake ASIN identification string and manually copying an image to the corresponding location inside the Kindle thumbnails folder.

func (*Book) OverrideTemplate

func (m *Book) OverrideTemplate(tpl template.Template) Book

OverrideTemplate overrides the template used in order to generate the skeleton section of a KF8 HTML chunk.

During conversion to a PalmDB database, this template is passed the internal inventory type. If the template cannot successfully be applied, the conversion will panic.

The skeleton section generally consists of a complete HTML document including head and body, with the body tag expected to contain an 'aid' attribute that indicates the identifier of the corresponding chunk. As it is relatively easy to end up with an invalid KF8 document by generating invalid skeleton sections, this option is private and hidden behind a setter function.

func (Book) Realize

func (m Book) Realize() pdb.Database

Realize converts a Book to a PalmDB Database.

type Chapter

type Chapter struct {
	Title  string
	Chunks []Chunk
}

Chapter represents a chapter in a Book.

type Chunk

type Chunk struct {
	Body string
}

Chunk represents a chunk of text in a Chapter.

Chunks are mostly an implementation detail that is exposed for maximum control over the final book output. Generally, you should use one of the various "Chunks" functions in order to generate the correct amount of chunks for a chapter.

func Chunks

func Chunks(strings ...string) []Chunk

Chunks produces a list of chunks from one or more strings.

In the resulting list of chunks, each chunk exactly corresponds the given string with the same index. In almost all cases, this is the preferred method of converting KF8 HTML into a list of chunks.

Notes

Bugs

• While the MOBI language format supports regions, this implementation does not and explicitly removes region information from the locale stored in the generated MOBI file.