Book Configuration Specification

André Alves Garzia
Download the eBook

Table Of Contents

  1. Introduction
  2. Using TOML
  3. Metadata Section
  4. Default values
  5. Title
  6. Subtitle
  7. Date
  8. Identifier
  9. Cover
  10. Language
  11. License
  12. Author Section
  13. Default values
  14. Name
  15. Bio
  16. Photo
  17. Book Section
  18. Default values
  19. Enabled
  20. Theme
  21. Frontmatter and Backmatter
  22. Chapters
  23. Important remarks
  24. Table of Contents Section
  25. Default values
  26. Prefix
  27. Label
  28. Match
  29. Important remarks
  30. Publisher Section
  31. Default values
  32. Name
  33. Bio
  34. Link
  35. Site Section
  36. Default values
  37. Enabled
  38. Theme
  39. Frontmatter, Chapters, and Backmatter
  40. Blurb
  41. Landing
  42. Download
  43. Site Actions
  44. Site labels
  45. WebMonetization Section
  46. Default values
  47. Endpoint
  48. Call To Action Section
  49. Default values
  50. cta
  51. url
  52. label
  53. Links Section
  54. Default values
  55. cta
  56. url
  57. label
  58. Using YAML
  59. Why We Prefer TOML over YAML
  60. Sample configuration using YAML
  61. Using JSON
  62. Why We Prefer TOML over JSON
  63. Sample configuration using JSON
  64. Final Remarks and Moving On

Metadata Section

The metadata section contains fields that would be used for archival purposes in a library or shop.

Default values

Each of these fields has a sensible default value, so you should only fill the ones you need. Below is a metadata section with the default values being explicitly shown:

[[ metadata ]]
title = "Untitled Book"
subtitle = false
date = new Date()
identifier = false
cover = false
language = "en"
license = false

If you don’t add a field to your Book.toml file, their default value will be used. Usually, if the default value is false it means that the value is ignored.

The software developers among you might have noticed that the fields change type from boolean: false to a string when filled in. That is by design and makes checking for them in templates easier.

Title

You book’s title. This is added to both the eBook and the Website.

Example:

title = "Moby Dick, or, The Whale"

Subtitle

An optional field to hold your book subtitle. If it is present, it is added to both the eBook and the Website.

Example:

subtitle = "That classic book about a whale you have to read for school"

Date

The publication date for the book. The default value will make it the current date when you’re generating the book. If you want to fill it in, you need to write the date in ISO 8601 format.

Example:

date = 2019-08-08T12:00:00Z

It is <year>-<month>-<day>T<hour>:<minute>:<seconds>Z. The year should always be four numbers, and all the other items should be two numbers, so put a leading zero if the value is below ten.

Identifier

This is the unique identifier that will be used to identify your book. This can be an ISBN, or any other unique value that is compatible with the platforms you’ll distribute your eBook on. A unique URL pointing to your book is a good identifier.

Example:

identifier = "http://www.gutenberg.org/ebooks/2701"

Cover

The cover image file for the book. This file, like all other images in your book, should be placed inside a folder called images inside your manuscript folder.

cover = "images/cover.jpg"

Language

The language the book is written in. The value for this field should be in ISO 639-1 format, which is a two letter code to represent a language.

Here are some of example language codes:

Language ISO 639-1 Code
English en
Chinese zh
Spanish es
Portuguese pt
German de
Italian it
Swahili sw
Korean ko
Japanese ja
French fr
Xhosa xh
Guarani gn

Example:

language = "pt"

License

This is the license for your book. It can be an HTML chunk if you want to add an image and link to the license. The intended use case for this is so that it becomes easier to tell the reader that your book is using copyleft licenses such as Creative Commons.

Be aware that Little Webby Press does not generate a copyright page for your book. You should do it yourself, and add it to the frontmatter.

The value of this license field is used only on the Website landing page.

Example:

license = "<a href='https://creativecommons.org/licenses/by-nc/4.0/deed.en_GB'><img src='book/images/license.svg'></a>"

The example above is a bit complex, it uses an HTML chunk to create a link to the Creative Commons Website page for a specific version of the license, and it uses an image that is in the manuscript folder.

←
→