Let’s write books in HTML! HTMLBook is an open, XHTML5-based standard for the authoring and production of both print and digital books. HTMLBook is built on the following premises:

As such, HTMLBook can be characterized in the following ways:

Notes on the HTMLBook Specification

Requirements for HTML5 elements in the HTMLBook specification are below. Special semantic inflections for data-type attributes, unless otherwise noted, come from EPUB 3 Structural Semantics Vocabulary

Many content models refer to “Block Elements” or “Inline Elements”; please see Block Elements and Inline Elements for the corresponding list of HTML5 elements that belong to each of these categories.

If no content model or attribute requirements are explicitly specified, then HTMLBook adopts the corresponding requirements in the [[!HTML5]] Specification

Revision History and Notes

16 September 2015
Added informative section on reference entries
25 February 2015
Clarified HTMLBook specifications for inline semantics/tagging
8 April 2014
Updated specifications for section subtitles to comply with best practices set forth in “Common idioms without dedicated elements” in [[!HTML5]] Specification.
29 December 2013
Minor revisions for clarity
13 August 2013
Revised specification for footnote markup
3 July 2013
Changed spec to use the attribute data-type for specifying book-specific semantics instead of class. The class attribute is now free to be used for whatever user-defined semantics are desired, and there are no restrictions on class values. Users of the spec may want to replicate data-type values in the class attribute to facilitate CSS styling, but this is completely optional.
19 April 2013
First release of Working Draft

Book Component elements

Book

HTML element: <body>

Attribute requirements: data-type="book" (Not in [[EPUB3SSV]]; from [[DOCBOOK]])

Content model: Optional <h1> that contains book title, or Header block that contains book title and optional subtitle content; then one or more Book Component elements as children (<div> for Part elements, <nav> for Table of Contents, and <section> elements for all other book divisions)

Example 

<body data-type="book">
  <h1>jQuery Cookbook</h1>
  <section data-type="chapter">
    <!-- Chapter content here -->
  </section>
</body>

Note: Just as in standard HTML5, <body> is a child of the root <html> element.

Chapter

HTML element: <section>

Attribute requirements: data-type="chapter"

Content model: First child must be either <h1> that contains chapter title, or Header block that contains chapter title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="chapter">
  <!-- h1 used for all chapter titles -->
  <h1>Chapter Title</h1>
  <p>Chapter content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Appendix

HTML element: <section>

Attribute requirements: data-type="appendix" or data-type="afterword", depending on content

Content model: First child must be either <h1> that contains appendix title, or Header block that contains appendix title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="appendix">
  <h1>Appendix Title</h1>
  <p>Appendix content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Bibliography

HTML element: <section>

Attribute requirements: data-type="bibliography"

Content model: First child must be either <h1> that contains bibliography title, or Header block that contains bibliography title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="bibliography">
  <h1>Bibliography Title</h1>
  <p>Bibliography content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Glossary

HTML element: <section>

Attribute requirements: data-type="glossary"

Content model: First child must be either <h1> that contains glossary title, or Header block that contains glossary title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Best practices: List of glossary terms should be marked up using <dl> elements with a data-type of "glossary", with <dt> children with a data-type of "glossterm" and <dd> children with a data-type of "glossdef". Term text should be wrapped in a <dfn>. However, none of this is formally required by the spec.

Example 

<section data-type="glossary">
  <h1>Glossary Title</h1>
  <dl data-type="glossary">
    <dt data-type="glossterm">
      <dfn>jQuery</dfn>
    </dt>
    <dd data-type="glossdef">
      Widely used JavaScript library
    </dd>
   </dl>
</section>

Preface

HTML element: <section>

Attribute requirements: data-type="preface", data-type="foreword", or data-type="introduction", depending on content

Content model: First child must be either <h1> that contains preface title, or Header block that contains preface title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="preface">
  <h1>Preface Title</h1>
  <p>Preface content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Frontmatter

HTML element: <section>

Attribute requirements: data-type="halftitlepage", data-type="titlepage", data-type="copyright-page", or data-type="dedication", depending on content

Content model: First child must be either <h1> that contains frontmatter section title, or Header block that contains frontmatter title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="titlepage">
  <h1>Python in a Nutshell</h1>
  <p>By Alex Martelli</p>
</section>

Backmatter

HTML element: <section>

Attribute requirements: data-type="colophon", data-type="acknowledgments", data-type="afterword", or data-type="conclusion", depending on content

Content model: First child must be either <h1> that contains backmatter section title, or Header block that contains backmatter title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example 

<section data-type="colophon">
  <h1>Colophon Title</h1>
  <p>Colophon content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Part

HTML element: <div>

Attribute requirements: data-type="part"

Content model: First child must be either <h1> that contains part title, or Header block that contains part title and optional subtitle content; then zero or more Block Elements that compose the optional Part introduction; then one or more <section> elements representing Book Component children other than a Part

Example 

<div data-type="part">
  <h1>Part One: Introduction to Backbone.js</h1>
  <p>Part Introduction...</p>
  <section data-type="chapter">
    <!-- Chapter content here -->
  </section>
</div>

Table of Contents

HTML element: <nav>

Attribute requirements: data-type="toc"

Content Model: The TOC must be conformant to the specs for the [[EPUB3]] Navigation document. First child is zero or more Heading elements (<h1>-<h6>), followed by an <ol> (with <li> children that can contain only a <span> element or an <a> element plus an optional <ol> child)

Example 

<nav data-type="toc">
  <h1>Table of Contents</h1>
   <ol>
     <li><a href="examples_page.html">A Note Regarding Supplemental Files</a></li>
     <li><a href="pr02.html">Foreword</a></li>
     <li><a href="pr03.html">Contributors</a>
       <ol>
         <li><a href="pr03.html#I_sect1_d1e154">Chapter Authors</a></li>
         <li><a href="pr03.html#I_sect1_d1e260">Tech Editors</a></li>
       </ol>
     </li>
  </ol>
</nav>

Index

HTML element: <section>

Attribute requirements: data-type="index"

Content model: First child must be either <h1> that contains index title, or Header block that contains index title and optional subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Best practices: HTMLBook recommends following the [[EPUBINDEX]] specification and using <ol>/<li> elements for marking up index entries, with data-type attributes used for semantic inflection as appropriate, but none of this is a formal spec requirement

Example 

<section data-type="index">
  <h1>Index Title</h1>
  <div data-type="index-group">
    <h2>A</h2>
    <ol>
      <li data-type="index-term">AsciiDoc, <a href="ch01#asciidoc" data-type="index-locator">All about AsciiDoc</a>
	<ol>
           <li data-type="index-term">conversion to HTML, 
             <a href="ch01#asctohtml" data-type="index-locator">AsciiDoc Output Formats</a>
           </li>
         </ol>
      </li>
      <li data-type="index-term">azalea, <a href="ch01#azalea" data-type="index-locator">Shrubbery</a></li>
    </ol>
  </div>
</section>

Sections

HTML element: <section>

Attribute requirements: data-type="sect1", data-type="sect2", data-type="sect3", data-type="sect4", data-type="sect5" (From [[DOCBOOK]] vocabulary), depending on hierarchy level. sect1 is used for <section> elements nested directly in main Book Components ("chapter", "appendix", etc.). sect2 is used for <section> elements nested in a sect1 <section>, sect3 is used for <section> elements nested in a sect2 <section>, and so on.

Content model: The first child must either be a main heading element corresponding to the hierarchy level indicated by data-type value, as follows:

"sect1" -> h1
"sect2" -> h2
"sect3" -> h3
"sect4" -> h4
"sect5" -> h5

or a Header block that contains section title and optional subtitle content. This is followed by zero or more Block Elements, followed by zero or more <section> elements with a data-type value one level lower in the hierarchy, as long as the parent section is a "sect4" or higher (e.g., <section data-type="sect4"> nested in <section data-type="sect3">)

Example:

<section data-type="sect1">
  <h1>A-Head</h1>
  <p>If you httpparty, you must party hard</p>
  <!-- Some more paragraphs -->
  <section data-type="sect2">
    <h2>B-Head</h2>
    <p>What's the frequency, Kenneth?</p>
    <!-- And so on... -->
  </section>
</section>

Block Elements

Paragraph

HTML element: <p>

Example:

<p>This is a standard paragraph with some <em>emphasized text</em></p>

Sidebar

HTML element: <aside>

Attribute requirements: data-type="sidebar"

Content model: Zero or one <h5> element that contains the sidebar title); then zero or more Block Elements

Example:

<aside data-type="sidebar">
  <h5>Amusing Digression</h5>
  <p>Did you know that in Boston, they call it "soda", and in Chicago, they call it "pop"?</p>
</aside>

Admonitions

HTML element: <div>

Attribute requirements: data-type="note", data-type="warning", data-type="tip", data-type="caution", or data-type="important", depending on the content within

Content model: Either of the following content models is acceptable:

Examples:

<div data-type="note">
  <h1>Helpful Info</h1>
  <p>Please take note of this important information</p>
</div>
<div data-type="warning">Make sure to get your AsciiDoc markup right!</div>

Tables

HTML element: <table>

Content model: Zero or one <caption> elements (for titled/captioned tables); then zero or more <colgroup> elements; then zero or more <thead> elements; then a choice between either zero or more <tbody> elements, or zero or more <tr> elements; then zero or more <tfoot> elements

Content model for <caption>: Either of the following is acceptable:

Content model for <colgroup>: Mirrors [[HTML5]] Specification

Content models for <thead>, <tbody>, and <tfoot>: Mirror [[HTML5]] Specification

Content model for <tr>: Mirrors [[HTML5]] Specification, but see content model below for rules for child <td> and <th> elements

Content model for <td> and <th> elements: Either of the following is acceptable:

Examples:

<table>
<caption>State capitals</caption>
<tr>
  <th>State</th>
  <th>Capital</th>
</tr>
<tr>
  <td>Massachusetts</td>
  <td>Boston</td>
</tr>
<!-- And so on -->
</table>
<table>
  <thead>
    <tr>
      <th>First</th>
      <th>Middle Initial</th>
      <th>Last</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alfred</td>
      <td>E.</td>
      <td>Newman</td>
    </tr>
    <!-- And so on -->
  </tbody>
</table>

Figures

HTML element: <figure>

Content model: Either of the following is acceptable:

Example:

<figure>
<figcaption>Adorable cat</figcaption>
<img src="cute_kitty.gif" alt="Photo of an adorable cat"/>
</figure>

Examples

HTML element: <div>

Attribute requirements: data-type="example"

Content model: Either of the following content models is acceptable:

Example:

<div data-type="example">
<h5>Hello World in Python</h5>
<pre data-type="programlisting">print "Hello World"</pre>
</div>

Code listings

HTML element: <pre>

Attribute requirements: data-type="programlisting"

Optional HTMLBook-specific attribute: data-code-language, used to indicate language of code listing (e.g., data-code-language="python")

Example:

<pre data-type="programlisting">print "<em>Hello World</em>"</pre>

Ordered lists

HTML element: <ol>

Content model: Zero or more <li> children for each list item

Content model for <li> children: Either of the following is acceptable:

Example:

<ol>
<li>Step 1</li>
<li>
  <p>Step 2</p>
  <p>Step 2 continued</p>
</li>
<!-- And so on -->
</ol>

Itemized lists

HTML element: <ul>

Content model: Zero or more <li> children for each list item

Content model for <li> children: Either of the following is acceptable:

Example:

<ul>
<li>Red</li>
<li>Orange</li>
<!-- And so on -->
</ul>

Definition lists

HTML element: <dl>

Content model: Mirrors [[HTML5]] Specification

Content model for <dt> children: text and/or zero or more Inline Elements

Content model for <dd> children: Either of the following is acceptable:

Example:

<dl>
  <dt>Constant Width Bold font</dt>
  <dd>Used to indicate user input</dd>
</dl>

Blockquote

HTML element: <blockquote>

Content model: Either of the following is acceptable:

Example:

<blockquote>
  <p>When in the course of human events...</p>
  <p data-type="attribution">U.S. Declaration of Independence</p>
</blockquote>

Note: If the blockquote is an epigraph, add data-type="epigraph", e.g.:

<section data-type="chapter">
  <h1>Conclusion</h1>
  <blockquote data-type="epigraph">
    <p>It ain't over till it's over.</p>
    <p data-type="attribution">Yogi Berra</p>
  </blockquote>
  <p>In this final chapter of the book, we will…<p>
</section>

Equation

HTML element: <div>

Attribute requirements: data-type="equation" (From [[DOCBOOK]]; no close match in [[EPUB3SSV]])

Note: HTMLBook supports embedded MathML in HTML content documents, which can be used here.

Example:

<div data-type="equation">
<h5>Pythagorean Theorem</h5>
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <msup><mi>a</mi><mn>2</mn></msup>
  <mo>+</mo>
  <msup><mi>b</mi><mn>2</mn></msup>
  <mo>=</mo>
  <msup><mi>c</mi><mn>2</mn></msup>
</math>
</div>

Reference Entries (refentries)

Suggested HTML element: <div>

Suggested semantics: class="refentry"

Note: HTMLBook does not currently normatively specify structural semantics for reference entries as they are conceived in DocBook ([[DOCBOOK]]) or DITA ([[DITA]]). Use of <div class="refentry"> is suggested for marking up reference entries. The following example illustrates XHTML5 markup one might use for refentry content, which captures DocBook-style semantics

Example refentry paralleling [[DOCBOOK]]:

<div class="refentry">
  <header>
    <p class="refname">print</p>
    <p class="refpurpose">Output some text to stdout.</p>
  </header>
  <div class="refsynopsisdiv">
    <pre class="synopsis">print "<em>Hello World</em>"</pre>
  </div>
  <div class="refsect1">
    <h6>Description</h6>
    <p>More description would go here</p>
  </div>
</div>

Inline Elements

HTMLBook is primarily focused on codifying structural semantics for book authoring, and as such, it does not formally define specifications for phrase-level semantics (such as the DocBook varname or personname elements) beyond that which is codified in the [[!HTML5]] specification. Nor does it formally define specifications for purely presentational markup (such as underline or strikethrough rendering). HTMLBook users are encouraged to employ the appropriate standard HTML5 phrasing elements for inline semantics when available (e.g., <strong>, <em>, <s>, <u>) and to use <span> elements with custom-defined classes in other cases, as illustrated in the following examples.

Emphasis (generally for italic)

HTML element: <em>

Example:

<p>I <em>love</em> HTML!</p>

Strong (generally for bold)

HTML element: <strong>

Example:

<p>I <strong>love</strong> HTML!</p>

Literal (for inline code elements: variables, functions, etc.)

HTML element: <code>

Example:

<p>Enter <code>echo "Hello World"</code> on the command line</p>

General-purpose phrase markup for other styling

HTML element: <span>

Example:

<p>Use your own class attributes for custom styling for formatting 
like <span class="underline">underlined text</span></p>

Footnote, endnote

HTML element: <span>

Attribute requirements: data-type="footnote"

Content model: text and/or zero or more Inline Elements

Example:

<p>Five out of every six people who try AsciiDoc prefer it to 
Markdown<span data-type="footnote">Totally made-up statistic</span></p>

Notes:

Cross-references

HTML element: <a>

Attribute requirements: data-type="xref" (From [[DOCBOOK]]); an href attribute that should point to the id of a local HTMLBook resource referenced; data-xrefstyle (optional) for specifying the style of XREF

Example:

<section id="html5" data-type="chapter">
  <h1>Intro to HTML5<h1>
  <p>As I said at the beginning of <a data-type="xref" href="#html5">Chapter 1</a>, HTML5 is great...</p>
  <!-- Blah blah blah -->
</section>

Index Term

HTML element: <a>

Attribute requirements: data-type="indexterm"; for primary index entry value, use data-primary; for secondary index entry value, use data-secondary; for tertiary index entry value, use data-tertiary; for a "see" index reference, use data-see; for a "see also" index reference, use data-seealso; for a "sort" value to indicate alphabetization, use data-primary-sortas, data-secondary-sortas, or data-tertiary-sortas; for an "end-of-range" tag that marks the end of an index range, use data-startref="id_of_opening_index_marker" (Semantics from [[DOCBOOK]])

Content model: Empty

Example:

<p>The Atlas build system<a data-type="indexterm" data-primary="Atlas" data-secondary="build system"/> lets 
you build EPUB, Mobi, PDF, and HTML content</p>

Superscripts

HTML element: <sup>

Example:

<p>The area of a circle is πr<sup>2</sup></p>

Subscripts

HTML element: <sub>

Example:

<p>The formula for water is H<sub>2</sub>O</p>

Heading Elements

Headings

HTML elements: <h1>, <h2>, <h3>, <h4>, <h5>, or <h6>

Content Model: text and/or zero or more Inline Elements

Notes: Many main book components (e.g., chapters, parts, appendixes) require headings. The appropriate element from <h1>–<h6> is outlined below, as well as in the corresponding documentation for these components:

book title -> h1
part title -> h1
chapter title -> h1
preface title -> h1
appendix title -> h1
colophon title -> h1
dedication title -> h1
glossary title -> h1
bibliography title -> h1
sect1 title -> h1
sect2 title -> h2
sect3 title -> h3
sect4 title -> h4
sect5 title -> h5
sidebar title -> h5

Header

HTML element: <header>

Content Model: A Heading element at the proper level designated (h1–h5) for the parent Book Component, as outlined in the previous Headings section (e.g., an <h1> for a chapter <header>); then zero or more <p> elements for subtitles or author attributions, each of which must have a data-type of either subtitle or author

Example:

<section data-type="chapter">
  <header>
    <h1>Chapter title</h1>
    <p data-type="subtitle">Chapter subtitle</p>
  </header>
  <!-- Chapter content here... -->
</section>

Interactive Elements

Video

HTML element: <video>

Example:

Note: Fallback content is strongly recommended for output formats that do not support HTML5 interactive content

<video id="asteroids_video" width="480" height="270" controls="controls" poster="images/fallback_image.png">
<source src="video/html5_asteroids.mp4" type="video/mp4"/>
<source src="video/html5_asteroids.ogg" type="video/ogg"/>
<em>Sorry, the &lt;video&gt; element not supported in your
  reading system. View the video online at http://example.com.</em>
</video>

Audio

HTML element: <audio>

Note: Fallback content is strongly recommended for output formats that do not support HTML5 interactive content

Example:

<audio id="new_slang">
<source src="audio/new_slang.wav" type="audio/wav"/>
<source src="audio/new_slang.mp3" type="audio/mp3"/>
<source src="audionew_slang.ogg" type="audio/ogg"/>
<em>Sorry, the &lt;audio&gt; element is not supported in your
  reading system. Hear the audio online at http://example.com.</em>
</audio>

Canvas

HTML element: <canvas>

Notes: Should include fallbacks for environments that don’t support HTML5 or JavaScript (e.g., link or image). You may include <script> elements in your HTMLBook document <head> elements to include/reference JS code for Canvas handling.

Examples:

<canvas id="canvas" width="400" height="400">
 Your browser does not support the HTML 5 Canvas. See the interactive example at http://example.com.
</canvas>

Comments

To add comments to an HTMLBook document, either use standard HTML/XML comment syntax:

<!-- This is a comment -->

Or add a data-type="comment" attribute to any HTML element, e.g.:

<div data-type="comment">This is a comment preceding a paragraph of text</div>
<p>This is a paragraph of text <span data-type="comment">Inline comment in paragraph</span></p>

Metadata

Metadata points

HTML element: <meta>

Attribute requirements: name (for name of metadata point); content (for value of metadata point)

Content model: Empty

Note: All <meta> elements must be children of the <head> element of the HTML file.

Example:

<head>
  <title>Title of the Book</title>
  <meta name="isbn-13" content="9781449344856"/>
</head>

Element Classification

Block Elements

In HTMLBook, the majority of elements classified by the HTML5 specification as Flow Content (minus elements also categorized as Heading Content, Phrasing Content, and Sectioning Content) are considered to be Block Elements. Here is a complete list:

Inline Elements

In HTMLBook, the majority of elements classified by the HTML5 specification as Phrasing Content are considered to be Inline Elements. Here is a complete list: