Filesystem Layout and File Naming Conventions
A bare Standard Ebooks directory structure looks like this:
File locations
XHTML files containing the actual text of the ebook are located in
./src/epub/text/
. All files in this directory end in.xhtml
.CSS files used in the ebook are located in
./src/epub/css/
. All files in this directory end in.css
. This directory contains only three CSS files:./src/epub/css/core.css
is distributed with all ebooks and is not edited../src/epub/css/se.css
is also distributed with all ebooks and is not edited../src/epub/css/local.css
is used for custom CSS local to the particular ebook.
Raw source images used in the ebook, but not distributed with the ebook, are located in
./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:./images/titlepage.svg
is the editable titlepage file that is later compiled for distribution../images/cover.svg
is the editable cover file that is later compiled for distribution../images/cover.source.(jpg|png|bmp|tif)
is the raw cover art file that may be cropped, resized, or otherwise edited to create./images/cover.jpg
../images/cover.jpg
is the final edited cover art that will be compiled into./src/epub/images/cover.svg
for distribution.
Images compiled or derived from raw source images, that are then distributed with the ebook, are located in
./src/epub/images/
.The table of contents is located in
./src/epub/toc.xhtml
.The epub metadata file is located in
./src/epub/content.opf
.The ONIX metadata file is located in
./src/epub/onix.xml
. This file is identical for all ebooks.The
./src/META-INF/
and./src/mimetype
directory and files are epub structural files that are identical for all ebooks.The
./LICENSE.md
contains the ebook license and is identical for all ebooks.
XHTML file naming conventions
Numbers in filenames don’t include leading
0
s.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
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
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.
Chapters not contained in separate volumes are named
chapter-N.xhtml
, whereN
is the chapter number starting at1
.Section Filename Chapter 1 chapter-1.xhtml
Chapter 2 chapter-2.xhtml
Chapters contained in separate volumes, where the chapter number re-starts at 1 in each volume, are named
chapter-X-N.xhtml
, whereX
is the part number starting at1
, andN
is the chapter number within the part, starting at1
.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
Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named
chapter-N.xhtml
, whereN
is the chapter number, starting at1
.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
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
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
If a work contains more than one section of the same type (for example multiple prefaces), the filename is followed by
-N
, whereN
is a number representing the order of the section, starting at1
.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
If a work contains images other than the cover art, the filename of each image should be
illustration-
followed by-N
, whereN
is a number representing the image’s order of appearance in the work, starting at1
.
The se-lint-ignore.xml
file
The se lint
tool makes best guesses to alert the user to potential issues in an ebook production, and it may sometimes guess wrong. An se-lint-ignore.xml
file can be placed in the ebook root to make se lint
ignore specific error numbers in an ebook.
se-lint-ignore.xml
is optional. If it exists, it is in the ebook root.An empty
se-lint-ignore.xml
file looks like this:The
<se-lint-ignore>
root element contains one or more<file>
elements.<file>
elements have apath
attribute containing a filename to match in./src/epub/text/
.path
attributes accept shell-style globbing to match files.Each
<file>
element contains one or more<ignore>
elements. Each<ignore>
element contains one<code>
element and one<reason>
element.The value of
<code>
is the error/warning code provided byse lint
. This code will be ignored for its parent file(s) whense lint
is next run.The value of
<reason>
is a prose explanation about why the code was ignored. This aids future producers or reviewers in understanding the reasoning behind why an error code was ignored.<reason>
is required to have a non-whitespace value.
Example
The following is an example of a complete se-lint-ignore.xml
file from Tractatus Logico-Philosophicus.