'2. Filesystem Layout and File Naming Conventions - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>

Filesystem Layout and File Naming Conventions

Filenames aim to be clear, common-sense descriptions of their contents.

File locations

  1. XHTML files containing the actual text of the ebook are located in ./src/epub/text/. All files in this directory end in .xhtml.
  2. CSS files used in the ebook are located in ./src/epub/css/. All files in this directory end in .css. This directory contains only two CSS files:
    1. ./src/epub/css/core.css is distributed with all ebooks and is not meant to be edited.
    2. ./src/epub/css/local.css is used for custom CSS local to the particular ebook.
  3. Raw source images used in the ebook, but not distributed with the ebook, are located in ./src/images/. These images may be, for example, very high resolution that are later converted to lower resolution for distribution, or raw bitmaps that are later converted to SVG for distribution. Every ebook contains the following images in this directory:
    1. ./src/images/titlepage.svg is the editable titlepage file that is later compiled for distribution.
    2. ./src/images/cover.svg is the editable cover file that is later compiled for distribution.
    3. ./src/images/cover.source.(jpg|png|bmp|tiff) is the raw cover art file that may be cropped, resized, or otherwise edited to create ./src/images/cover.jpg.
    4. ./src/images/cover.jpg is the final edited cover art that will be compiled in to ./src/epub/images/cover.svg for distribution.
  4. Images compiled or derived from raw source images, that are then distributed with the ebook, are located in ./src/epub/images/.
  5. The table of contents is located in ./src/epub/toc.xhtml.
  6. The epub metadata file is located in ./src/epub/content.opf.
  7. The ONIX metadata file is located in ./src/epub/onix.xml. This file is identical for all ebooks.
  8. The ONIX metadata file is located in ./src/epub/onix.xml. This file is identical for all ebooks.
  9. The ./src/META-INF/ and ./src/mimetype directory and files are epub structural files that are identical for all ebooks.
  10. The ./LICENSE.md contains th ebook license and is identical for all ebooks.

XHTML file naming conventions

  1. Numbers in filenames don’t include leading 0s.
  2. Files containing a short story, essay, or other short work in a larger collection, are named with the URL-safe title of the work, excluding any subtitles.
    Work Filename
    A short story named “The Variable Man” the-variable-man.xhtml
    A short story named “The Sayings of Limpang-Tung (The God of Mirth and of Melodious Minstrels)” the-sayings-of-limpang-tung.xhtml
  3. Works that are divided into larger parts (sometimes called “parts,” “books,” “volumes,” “sections,” etc.) have their part divisions contained in individual files named after the type of part, followed by a number starting at 1.

    book-1.xhtml

    book-2.xhtml

    part-1.xhtml

    part-2.xhtml

  4. Works that are composed of chapters, short stories, essays, or other short- to medium-length sections have each of those sections in an individual file.
    1. Chapters not contained in separate volumes are named chapter-N.xhtml, where N is the chapter number starting at 1.
      Section Filename
      Chapter 1 chapter-1.xhtml
      Chapter 2 chapter-2.xhtml
    2. Chapters contained in separate volumes, where the chapter number re-starts at 1 in each volume, are named chapter-X-N.xhtml, where X is the part number starting at 1, and N is the chapter number within the part, starting at 1.
      Section Filename
      Part 1 part-1.xhtml
      Part 1 Chapter 1 chapter-1-1.xhtml
      Part 1 Chapter 2 chapter-1-2.xhtml
      Part 1 Chapter 3 chapter-1-3.xhtml
      Part 2 part-2.xhtml
      Part 2 Chapter 1 chapter-2-1.xhtml
      Part 2 Chapter 2 chapter-2-2.xhtml
    3. Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named chapter-N.xhtml, where N is the chapter number, starting at 1.
      Section Filename
      Part 1 part-1.xhtml
      Chapter 1 chapter-1.xhtml
      Chapter 2 chapter-2.xhtml
      Chapter 3 chapter-3.xhtml
      Part 2 part-2.xhtml
      Chapter 4 chapter-4.xhtml
      Chapter 5 chapter-5.xhtml
    4. Works that are composed of extremely short sections, like a volume of short poems, are in a single file containing all of those short sections. The filename is the URL-safe name of the work.
      Section Filename
      A book of short poems called “North of Boston” north-of-boston.xhtml
    5. Frontmatter and backmatter sections have filenames that are named after the type of section, regardless of what the actual title of the section is.
      Section Filename
      A preface titled “Note from the author” preface.xhtml
    6. If a work contains more than one section of the same type (for example multiple prefaces), the filename is followed by -N, where N is a number representing the order of the section, starting at 1.
      Section Filename
      The work’s first preface, titled “Preface to the 1850 Edition” preface-1.xhtml
      The work’s second preface, titled “Preface to the Charles Dickens Edition” preface-2.xhtml