Documentation
Table of Contents
Template
When building the Table of Contents the toc.xhtml file should be used. Along with this BBEdit template the pagebreak-builder.app can build and check the page numbers.
If there are any images or tables with ids the script toc-lists-builder.scpt will pull each and build the links in their supporting files (toc_images.xhtml and toc_tables.xhtml) where the bbprojectd exists.
If the toc_images.xhtml, toc_tables.xhtml and pagebreak.xhtml exist in the same directory as bbprojectd when the toc-builder.app is ran it will pull from each of these files and build the toc.xhtml and a toc_amazon.xhtml. The toc_amazon.xhtml pulls all information that isn't supported on Amazon.
Amazon
Due to regular issues with Amazon the epub:type's page-list, loi & lot are not to be included when compiling the Mobi. epub:type="lot" for videos shouldn’t be used as it will throw an error with epubcheck.
TOC
All elements of the TOC in a printed edition should be included in the epub:type="toc". There might be times when adding further navigation elements to the TOC could make the navigation experience better. If a printed edition does not exist then any headers within the content can be retrieved with regex and the navigation built. For example a 40 day devotional should have 40 a minimum of 40 entries.
Descriptive
If the printed PDF references generic navigation but elements are added to enhance the navigation then it should be added, example:
Printed edition has:
- Chapter 1
- Chapter 2
- Chapter 3
- Chapter 4
but when visiting the pages each chapter has a header than the toc should be added, example:
html1<li><a href="text/EK02_chapter01.xhtml">Chapter 1</a></li>2<li><a href="text/EK02_chapter02.xhtml">Chapter 2</a></li>3<li><a href="text/EK02_chapter03.xhtml">Chapter 3</a></li>4<li><a href="text/EK02_chapter04.xhtml">Chapter 4</a></li>
html1<li><a href="text/EK02_chapter01.xhtml">Chapter 1: Monday Blues</a></li>2<li><a href="text/EK02_chapter02.xhtml">Chapter 2: This too will pass</a></li>3<li><a href="text/EK02_chapter03.xhtml">Chapter 3: Almost Turkey Time</a></li>4<li><a href="text/EK02_chapter04.xhtml">Chapter 4: What is planned for 2021</a></li>
Nesting
Table of Contents entries that have children should be nested:
html1<nav epub:type="toc" id="toc">2<h1>Table of Contents</h1>3<ol id="tocList">4<li>5<a href="text/SC02_chapter01.xhtml#page1.xhtml">A linked heading</a>6<ol>7<li><a href="text/SC02_chapter02.xhtml#page21.xhtml">Sub section</a></li>8</ol>9</li>10<li>11An unlinked heading12<ol>13<li><a href="text/SC02_chapter03.xhtml#page41.xhtml">Sub section</a></li>14</ol>15</li>16</ol>17</nav>
If any children exist beyond the second layer then the id should be added to the XHTML because adding just the page number the actually entry could be several page views away, example:
html1<nav epub:type="toc" id="toc">2<h1>Table of Contents</h1>3<ol id="tocList">4<li>5<a href="text/SC02_chapter01.xhtml#page1.xhtml">A linked heading</a>6<ol>7<li>8<a href="text/SC02_chapter02.xhtml#page21.xhtml">Sub Section</a>9<ol>10<li><a href="text/SC02_chapter02.xhtml#subsub">Sub Sub section</a></li>11</ol>12</li>13</ol>14</li>15<li>16An unlinked heading17<ol>18<li><a href="text/SC02_chapter03.xhtml#page41.xhtml">Sub Section</a></li>19</ol>20</li>21</ol>22</nav>
Landmarks
epub:type="landmarks" is required by Amazon (fixed layout is an exception). The first entry in the TOC List should be coded as the first entry to the landmarks, example:
html1<nav epub:type="toc" id="toc">2<h1>Table of Contents</h1>3<ol id="tocList">4<li><a href="text/SC01_frontmatter05.xhtml#pageix">Acknowledgments</a></li>5<li><a href="text/SC02_chapter01.xhtml#page1">Chapter 1</a></li>6<li><a href="text/SC02_chapter02.xhtml#page21">Chapter 2</a></li>7<li><a href="text/SC02_chapter03.xhtml#page41">Chapter 3</a></li>8<li><a href="text/SC02_chapter04.xhtml#page61">Chapter 4</a></li>9<li><a href="text/SC02_chapter05.xhtml#page81">Chapter 5</a></li>10<li><a href="text/SC02_chapter06.xhtml#page99">Chapter 6</a></li>11<li><a href="text/SC02_chapter06.xhtml#page99">Appendix</a></li>12</ol>13</nav>14<nav epub:type="landmarks" class="hide">15<h1>Guide</h1>16<ol>17<li>18<a href="text/SC01_frontmatter05.xhtml#pageix" epub:type="bodymatter">Acknowledgments</a>19</li>20<li><a epub:type="toc" href="toc.xhtml">Table of Contents</a></li>21<!--must be in here to display in kindle which only picks up22toc under epub:type="landmarks">. Be sure to include nav.css to hide <ol> numbering. -->23</ol>24</nav>
Page List
If a printed version exists and pagebreaks are added to the content then a page list should be built for the Table of Contents.
html1<nav epub:type="page-list" class="hide">2<h1>Page Numbers</h1>3<ol>4<li><a href=".xhtml#page001">1</a></li>5<!-- remaining numbers -->6<li><a href=".xhtml#page010">10</a></li>7<!-- remaining numbers -->8<li><a href=".xhtml#page100">100</a></li>9</ol>10</nav>
List of Images
epub:type="loi" is required if you have images (fixed layout is an exception) and images that are educational or add value to the content should be used in this ePub type. Do not add the title page or ornaments to the ePub type, example:
html1<nav epub:type="loi" class="hide">2<h1>List of Images</h1>3<ol>4<li><a href="text/CG02_chapter05.xhtml#img234">Some where over the moon</a></li>5</ol>6</nav>
If an alt tag is generic for the image then a description should be edited.
List of Tables
epub:type="lot" is required if you have tables (do not include in Mobi), example:
html1<nav epub:type="lot" class="hide">2<h1>List of Tables</h1>3<ol></ol>4</nav>
If a table is an image it should be included in the lot and not the loi.