Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Book Dash books

We're creating simple HTML versions of Book Dash books for the web and ebooks.

To grab the finished HTML, see the website version of these files.


If you'd like to help grow and improve this collection:

Adding a book requires four components:

  • A folder in this repo, organised as english-title/language-code, e.g. sleepy-mr-sloth/en for the English edition of Sleepy Mr Sloth.
  • An file in that folder (containing the story text and links to images)
  • An images folder in that folder (containing JPGs of the front cover and book-page images)
  • Information (metadata) about the book stored in the repo's _config.yml file.

For technical background on how these files are organised, see the Electric Book Workflow.

Creating the file

Each book's file contains all the text and links to images for the story.

This file is written in markdown: a simple way to structure plain text, which a markdown processor can turn into web- and ebook-ready HTML automatically. You can read more about markdown here.

The best way to learn how to create a markdown file for a book is to look at an existing one. Here is the raw markdown for Sleepy Mr Sloth.

It's made of four components:

  1. The YAML header: the part between the three hyphens at the top of the file:

    title: Sleepy Mr Sloth
  2. The heading: # Sleepy Mr Sloth. In markdown, a first-level heading is indicated with a hash at the start of the line.

  3. A link to each image, including a short description of what's in the image:

    ![Mr Sloth is sleepy and yawning]({{ site.image-set }}/01.jpg)
  4. The text of the story, as plain lines of text. The image always precedes the text that relates to it. (This is because in any book we, especially children, always take in the image before we read the text on a page.)

Each of these elements must be separated by an empty line.


These digital versions include cover and story images, always saved as JPG.

  • Cover images are language-specific, JPG replicas of the front covers of the book in that language. Covers must always be saved as cover.jpg. Cover images are always square.
  • Story images do not include text, since all the text is in the story markdown/HTML. The should always be saved as two-digit numbered filenames in order: 01.jpg, 02.jpg, etc. The first image is the first story image in the book (i.e. not the book plate, endpapers, or title page). Story images are always landscape (a double-page-spread from the print version). There are almost always 12 story images.

This means that story images can be reused as is for each language. Although – since each translation has its own images folder – we can make exceptions if necessary and use language-specific variations, should they exist and be important for the story (e.g. a text-based sign in a picture).

When preparing images, aim for 100KB per image, and about 1000 pixels across (the longest side, which should almost always be the width of the image). This makes entire books about 1.2MB in size, which is already quite large. Downstream reusers can then choose to downsample or downsize images if necessary.

The easiest way to create story images is to export to JPEG from the InDesign file, with language layers hidden. If you use this option, we recommend the following export settings:

  • Export: Spreads
  • Quality: Medium
  • Format Method: Baseline
  • Resolution (ppi): 72
  • Color space: RGB
  • Embed Color Profile: sRGB checked
  • Anti-alias checked
  • Use Document Bleed Settings: unchecked
  • Simulate Overprint unchecked

Editing the metadata file

Each book's details are included in _data/meta.yml.

This file is fairly easy to understand just by reading through it. Each book's details are set in two levels:

  • Info that relates to the original and, therefore, all editions of a book (e.g. the original team that created it)
    • Info that relates to a specific translation (e.g. the language it's in).

Since even small mistakes in this file can break the whole website, only certain people are able to edit it.

As a contributor, you can:

  • create just the lines for your book and log them as an issue, or
  • if you are familiar with GitHub, you can fork the repo, make the changes, and submit them as a pull request.


All Book Dash content is licensed with a Creative Commons Attribution licence. If you contribute, you agree that your contributions carry the same license.