Style Manual

Coming soon...

XHTML and CSS code formatting style

The clean tool in the Standard Ebooks toolset formats XHTML code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.

XHTML formatting

The first line of all XHTML files is:

<?xml version="1.0" encoding="utf-8"?>
The second line of all XHTML files is (replace LANG with the appropriate language tag for the file):

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="LANG">
Tabs are used for indentation.
Tag names are lowercase.
Tags whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.

<p> It was a dark and stormy night... </p>

<p>It was a dark and stormy night...</p>

Attributes

Attributes are in alphabetical order.
Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags, where subtags are capitalized.

<section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>

<section epub:type="chapter" xml:lang="en-US">...</section>
The string utf-8 is lowercase.

CSS formatting

The first two lines of all CSS files are:

@charset "utf-8"; @namespace epub "http://www.idpf.org/2007/ops";
Tabs are used for indentation.
Selectors, properties, and values are lowercase.

Selectors

Selectors are each on their own line, directly followed by a comma or a brace with no whitespace inbetween.
Complete selectors are separated by exactly one blank line.

abbr.name{ white-space: nowrap; } strong{ font-weight: normal; font-variant: small-caps; }

abbr.name{ white-space: nowrap; } strong{ font-weight: normal; font-variant: small-caps; }
Closing braces are on their own line.

Properties

Properties are each on their own line (even if the selector only has one property) and indented with a single tab.

abbr.name{ white-space; nowrap; }

abbr.name{ white-space: nowrap; }
Properties are in alphabetical order, where possible.

This isn’t always possible if you’re attempting to override a previous style in the same selector, and in some other cases.
Properties are directly followed by a colon, then a single space, then the property value.
Property values are directly followed by a semicolon, even if it's the last value in a selector.

Filesystem layout

How to name files

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, where N is the chapter number starting at 1.

Chapters contained in separate volumes, where the chapter number starts at 1 for each separate 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.

Example	Filename
Part 1	`part-1.xhtml`
Chapter 1	`chapter-1-1.xhtml`
Chapter 2	`chapter-1-2.xhtml`
Chapter 3	`chapter-1-3.xhtml`
Part 2	`part-2.xhtml`
Chapter 1	`chapter-2-1.xhtml`
Chapter 2	`chapter-2-2.xhtml`
Chapter 3	`chapter-2-3.xhtml`

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.

Example	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`
Chapter 6	`chapter-6.xhtml`

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.

Example	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 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.

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.

Example	Filename
A preface titled "Note from the author"	`preface.xhtml`

If an ebook 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.

Example	Filename
The first preface in an ebook, titled "Preface to the 1850 Edition"	`preface-1.xhtml`
The second preface in an ebook, titled "Preface to the Charles Dickens Edition"	`preface-2.xhtml`

Semantic inflection

The epub spec allows for semantic inflection, which is a way of adding pertinent semantic metadata to certain elements. For example, you may want to convey that the contents of a certain <section> are actually a part of a chapter. You would do that by using the epub:type attribute:

<section epub:type="chapter">...</section>

The epub spec includes a list of supported keywords that you can use in the epub:type attribute. Use this vocabulary first, even if other vocabularies contain the same keyword.
If there's no appropriate keyword in the epub spec, next consult the z3998 vocabulary.

Keywords using this vocabulary are preceded by the z3998 namespace.

<blockquote epub:type="z3998:letter">...</blockquote>
If the z3998 vocabulary doesn't have an appropriate keyword, next consult the Standard Ebooks vocabulary.

Keywords using this vocabulary are preceded by the se namespace.

Unlike other vocabularies, the Standard Ebooks vocabulary is organized heirarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by ..

The <i epub:type="se:name.vessel.ship"><abbr class="initialism">HMS</abbr> Bounty</i>.
The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different.

<section epub:type="chapter z3998:letter">...</section>

General XHTML patterns

The id attribute

ids of <section>s

Each <section> has an id attribute identical to the filename containing the <section>, without the trailing extension.
In files containing multiple <section>s, each <section> has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension.

ids of other elements

Generally, elements that are not <section>s do not have an id attribute. However an id attribute might be necessary if a particular element is referenced in a link in a different location in the ebook; for example, if a certain paragraph is linked from an endnote.

If an element requires an id attribute, the attribute's value is the name of the tag followed by -N, where N is the sequence number of the tag start at 1.

<p>See <a href="#p-4">this paragraph</a> for more details.</p> <p>...</p> <p>...</p> <p id="p-4">...</p> <p>...</p>

<title> tags

The <title> tag contains an appropriate description of the local file only. It does not contain the book title.

Titles of files that are an individual chapter or part division

Convert chapter or part numbers that are in Roman numerals to decimal numbers. Do not convert other Roman numerals that may be in the chapter title.

<title>Chapter 10</title>
If a chapter or part has no subtitle, the <title> tag contains Chapter followed by the chapter number.

<title>Chapter 4</title>
If a chapter or part has a subtitle, the <title> tag contains Chapter, followed by the chapter number, followed by a colon and a single space, followed by the subtitle.

<title>Chapter 4: The Reign of Louis XVI</title>

Titles of files that are not chapter or part divisions

Files that are not a chapter or a part division, like a preface, introduction, or epigraph, have a <title> tag that contains the complete title of the section.

<title>Preface</title>
If a file contains a section with a subtitle, the <title> tag contains the title, followed by a colon and a single space, followed by the subtitle.

<title>Quevedo and His Works: With an Essay on the Picaresque Novel</title>

Ordered/numbered and unordered lists

All <li> children of <ol> and <ul> tags have at least one direct child block-level tag. This is usually a <p> tag. (But not necessarily; for example, a <blockquote> tag might also be appropriate.)

<ul>
<li>Don’t forget to feed the pigs.</li>
</ul>

<ul>
<li>
	<p>Don’t forget to feed the pigs.</p>
</li>
</ul>

Sectioning

Structural divisions in an ebook are each contained in their own <section> tag.
In <section>s that have titles, the first child element is an <h#> or a <header> element containing the section's title.
Typically an epub is divided into many different files. However, these files must be "recomposable" into a single HTML file by the recompose-epub tool.

To achieve recomposability, individual files that contain subsections also contain all of the direct parent <section> tags, with id and epub:type attributes identical to those parents.

For example, consider an ebook containing both a file named part-1.xhtml, the first part, and a file named chapter-1-1.xhtml, the first chapter of the first part. chapter-1-1.xhtml contains a <section> element for both the parent part, and the actual chapter:

<section id="part-1" epub:type="part"> <section id="chapter-1-1" epub:type="chapter"> <h3 epub:type="title z3998:roman">I</h3> ... </section> </section>

Parts of an ebook and their order

Frontmatter

Frontmatter includes these parts of a book, in no particular order:

Titlepage: An SE template containing an image with the title, author, and translator.
Imprint: An SE template containing information about Standard Ebooks and links to the source transcription and scans used to produce this ebook.
Dedication: A dedication from the author.
Epigraph: An opening poem or quotation.
Acknowledgements: A list of people that the author wishes to thank.
Foreword: An introduction to the text, written by someone besides the author.
Preface: An introduction to the text but standing outside of the text itself, written by the author. Often describes how a book came into being or to establish the author's credentials. "About the book as a book."
Introduction: An introduction to the text written, by the author. "About the content of the book."
Prologue: An opening to the text that establishes setting or mood, usually in the voice of the text.

Note that in a Standard Ebooks ebook, the copyright page is part of the backmatter and not the frontmatter.

Backmatter

Backmatter includes these parts of a book, in no particular order:

Epilogue: A conclusion to the text, usually in the voice of the text..
Afterword: A note from the author to conclude the text, outside of the text itself.
Endnotes: Any supplementary notes referenced in the text.
Colophon: A description of publishing details regarding the specific edition of the text, including credits or contributors.
Copyright page: Usually considered frontmatter in print texts, but considered backmatter in Standard Ebooks ebooks.

Ordering of sections

The first section of an ebook is titlepage.xhtml. This file is auto-generated by create-draft.
The second section of an ebook is imprint.xhtml. The imprint contains links to the source transcription and scans used to produce the Standard Ebooks edition.
Any frontmatter relevant to the text follows.
If there is frontmatter, then a half title page follows.
Half title page patterns

The half title page contains the work title and subtitle.
1. Half title pages without subtitles:
  
  <?xml version="1.0" encoding="utf-8"?> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> <head> <title>Half Title</title> <link href="../css/core.css" rel="stylesheet" type="text/css"/> <link href="../css/local.css" rel="stylesheet" type="text/css"/> </head> <body epub:type="frontmatter"> <section id="halftitlepage" epub:type="halftitlepage"> <h1 epub:type="fulltitle">Don Quixote</h1> </section> </body> </html>
2. Half title pages with subtitles:
  
  section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{ display: block; font-size: .75em; font-weight: normal; } <?xml version="1.0" encoding="utf-8"?> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> <head> <title>Half Title</title> <link href="../css/core.css" rel="stylesheet" type="text/css"/> <link href="../css/local.css" rel="stylesheet" type="text/css"/> </head> <body epub:type="frontmatter"> <section id="halftitlepage" epub:type="halftitlepage"> <h1 epub:type="fulltitle"> <span epub:type="title">The Book of Wonder</span> <span epub:type="subtitle">A Chronicle of Little Adventures at the Edge of the World</span> </h1> </section> </body> </html>
Bodymatter (the main text) follows the frontmatter and half title page.
After the bodymatter, backmatter within the text follows, for example an afterword, epilogue, or conclusion.
Endnotes follow the text's backmatter. Endnotes files are named endnotes.xhtml.
The colophon follows.
The uncopyright page follows the colophon.

Headers

<h#> tags (i.e., <h1>–<h6>) are used for headers of sections that are structural divisions of a document.

<h#> tags are not used for headers of components that are not in the table of contents. For example, they would not be used to mark up the the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.
A section containing an <h#> appears in the table of contents.
The book's title is implicitly at the <h1> level, even if not present in the ebook. Because of the implicit <h1>, all other sections begin at <h2>.
Each <h#> tag uses the correct number for the section's heading level in the overall book, not the section's heading level in the individual file.

For example, given an ebook with a file named part-2.xhtml containing:

<section id="part-2" epub:type="part"> <h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> </section>

Consider this example for the file chapter-2-3.xhtml:

<section id="part-2" epub:type="part"> <section id="chapter-2-3" epub:type="chapter"> <h1 epub:type="title z3998:roman">III</h1> ... </section> </section>

<section id="part-2" epub:type="part"> <section id="chapter-2-3" epub:type="chapter"> <h3 epub:type="title z3998:roman">III</h3> ... </section> </section>
Each <h#> tag has a direct parent <section> tag.

Header HTML patterns

Sections without titles:

<h2 epub:type="title z3998:roman">XI</h2>
Sections with titles but no ordinal (i.e. chapter) numbers:

<h2 epub:type="title">A Daughter of Albion</h2>
Sections with titles and ordinal (i.e. chapter) numbers:

span[epub|type~="subtitle"]{ display: block; font-weight: normal; } <h2 epub:type="title"> <span epub:type="z3998:roman">XI</span> <span epub:type="subtitle">Who Stole the Tarts?</span> </h2>
Sections titles and subtitles but no ordinal (i.e. chapter) numbers:

span[epub|type~="subtitle"]{ display: block; font-weight: normal; } <h2 epub:type="title"> <span>An Adventure</span> <span epub:type="subtitle">(A Driver’s Story)</span> </h2>
Sections that require titles, but that are not in the table of contents:

header{ font-variant: small-caps; margin: 1em; text-align: center; } <header> <p>The Title of a Short Poem</p> </header>

Play CSS: [epub|type~="z3998:drama"]{ border-collapse: collapse; } [epub|type~="z3998:drama"] tr:first-child td{ padding-top: 0; } [epub|type~="z3998:drama"] tr:last-child td{ padding-bottom: 0; } [epub|type~="z3998:drama"] td{ vertical-align: top; padding: .5em; } [epub|type~="z3998:drama"] td:last-child{ padding-right: 0; } [epub|type~="z3998:drama"] td:first-child{ padding-left: 0; } [epub|type~="z3998:drama"] td[epub|type~="z3998:persona"]{ hyphens: none; text-align: right; width: 20%; } [epub|type~="z3998:drama"] td p{ text-indent: 0; } table[epub|type~="z3998:drama"], [epub|type~="z3998:drama"] table{ margin: 1em auto; } [epub|type~="z3998:stage-direction"]{ font-style: italic; } [epub|type~="z3998:stage-direction"]::before{ content: "("; font-style: normal; } [epub|type~="z3998:stage-direction"]::after{ content: ")"; font-style: normal; } [epub|type~="z3998:persona"]{ font-variant: all-small-caps; }