epubjs
Version:
Render ePub documents in the browser, across many devices
210 lines (148 loc) • 14 kB
HTML
<html xmlns:epub="http://www.idpf.org/2007/ops" xmlns="http://www.w3.org/1999/xhtml"><head><title>Styling and Theming</title><link rel="stylesheet" type="text/css" href="epub.css"/></head><body data-type="book"><section data-type="chapter" epub:type="chapter" data-pdf-bookmark="Chapter 7. Styling and Theming"><div class="chapter" id="idm318832">
<h1 id="stylingandtheming"><span class="label">Chapter 7. </span>Styling and Theming</h1>
<p>A theme is a collection of designs used to style every output format of a book. For example, a single theme would include designs for a PDF, an EPUB (the format for the iPad, Nook, etc.), a MOBI (the format for the Kindle), and an HTML website. Each of these designs would have a consistent look and feel, but with slight modifications to optimize the design for the output format. (Read more about styling each format in the following sections.)</p>
<p>All of the Atlas output formats (PDF, EPUB, MOBI, and HTML) are powered by CSS, the standard styling language for the Web. You can write <a data-original-title="" title="" href="#cssthemes">an entirely new theme using CSS</a>, that can be used for multiple projects, by multiple people, or you can just add <a href="#csscustomizations">CSS customizations</a> for your specific project.</p>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>This documentation is not a comprehensive guide on how to write CSS, but rather how to set up CSS files to work with Atlas. There are lots of resources online to get you started with learning CSS, and of course O’Reilly has <a data-original-title="" href="http://shop.oreilly.com/category/browse-subjects/web-development/html-css.do" title="">many books on the subject</a>.</p>
</div>
<section data-type="sect1" data-pdf-bookmark="Themes"><div class="sect1" id="cssthemes">
<h1>Themes</h1>
<p>Atlas uses themes to style projects. Each theme is built with CSS and split into 4 pieces, for each of the different output formats: PDF, EPUB, MOBI, and HTML. Atlas has two default themes built in: <a data-original-title="" href="https://github.com/oreillymedia/atlas_trade_theme" title="">Trade</a> and <a data-original-title="" href="https://github.com/oreillymedia/atlas_tech1c_theme" title="">Technical</a>. Feel free to use these themes as examples when creating your new design.</p>
<section data-type="sect2" data-pdf-bookmark="Creating a New Theme"><div class="sect2" id="creatingthemes">
<h2>Creating a New Theme</h2>
<p>Every new theme should include the following:</p>
<ul>
<li>CSS to style the ebook and print PDFs</li>
<li>CSS to style the EPUB</li>
<li>CSS to style the MOBI (Kindle file format)</li>
<li>CSS to style an HTML website</li>
<li>An HTML file to add any extra header information or layout elements to the HTML website (optional)</li>
<li>Downloadable sample files for each format (optional)</li>
</ul>
<p>Every theme should live in its own Atlas repository, and you can create this theme repository the same way you create a new project. Click the “New Project” button on the Projects page, give your repository a name, and then in the Templates section, click “Advanced” and choose “Theme”. This will pre-populate your theme repository with all the necessary folders, and blank CSS files for each format.</p>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>You can also create a public theme on GitHub for use in Atlas. </p>
</div>
<p>Atlas expects themes to use a specific file structure, so if you aren’t creating the theme via Atlas (as described above), then you’ll need to make sure to set your theme up accordingly, as shown in the figure below.</p>
<figure><div class="figure"><img class="iassetsimagescss-themes-01png" src="assets/css-themes-01.png"/>
<h6><span class="label">Figure 7-1. </span>The file structure for Atlas themes.</h6>
</div></figure>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Styling for PDF Output"><div class="sect2" id="idm375024">
<h2>Styling for PDF Output</h2>
<p>Atlas combines CSS with PDF processing software to create PDFs suitable for digital reading or professional printed books.</p>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>The specific PDF processing software we use is called Antenna House--you can read the documentation about Antenna House <a href="http://www.antennahouse.com/product/ahf60/docs/index.html">here</a>.</p>
</div>
<p>Creating a PDF with CSS relies on the <a data-original-title="" href="http://www.w3.org/TR/css3-page/" title="">Paged Media module</a>. For a primer on writing CSS for PDFs, read <a data-original-title="" href="http://alistapart.com/article/building-books-with-css3" title="">“Building Books with CSS 3”</a> on A List Apart, or <a data-original-title="" href="http://chimera.labs.oreilly.com/books/1234000001694" title="">watch the presentation here</a>.</p>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Styling for EPUB Output (iPad, Nook, etc.)"><div class="sect2" id="idm131056">
<h2>Styling for EPUB Output (iPad, Nook, etc.)</h2>
<p>Right now, the EPUB format is largely targetted at continuous, linear reading--creating more intricately-laid out files is fairly difficult, and getting these files to work on all the different eReading devices is even harder. There are a wide range of devices used to display EPUB files--the iPad, Sony Reader, and Nook, to name a few--and each of these devices offers a different level of support for CSS properties and selectors. Because of this, we advise you not to get too complex when styling for EPUB output. Here are a few CSS tips to get your EPUB files to display correctly, on all devices:</p>
<ul>
<li>Keep all text in a single column</li>
<li>Don’t rely on floats or absolute positioning</li>
<li>Page margins are off-limits on most devices</li>
<li>Not all devices render background colors or borders</li>
<li>Not all devices support less-common text styles (like text-transform)</li>
</ul>
<p>It’s a good idea to test your EPUB styles on all devices that you think your readers might use, if you can. The easiest way to test is simply to create an EPUB file using your CSS, and see how that file looks on each device.</p>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Styling for MOBI Output (Kindle)"><div class="sect2" id="idm125408">
<h2>Styling for MOBI Output (Kindle)</h2>
<p>Designing for Kindle is very similar to designing for EPUB: most new Kindle devices can render CSS and HTML quite well--on the same level as EPUB readers. This means that you can generally use the same CSS styles for both your MOBI and EPUB formats.</p>
<p>However, there are still a lot of older Kindle devices in use in the world, like the Kindle Keyboard. These devices have much more limited support for CSS styles, and so it’s generally a good idea to add an extra section of basic fallback styles for these devices, inside a media query, as shown in the following example.</p>
<pre class="prettyprint" data-original-title="" title="">
@media amzn-mobi {
h1 {
font-family: serif;
font-size: 200%;
}
h2 {
font-family: serif;
font-size: 150%;
}
h3 {
font-family: serif;
font-size: 125%;
}
h4 {
font-family: serif;
font-size: 120%;
}
}
</pre>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>If you don’t want to add extra fallback styles for older Kindle devices, don’t worry--we’ll add some default styles for you if we don’t see the media query in your mobi.css file.</p>
</div>
<aside data-type="sidebar" epub:type="sidebar"><div class="sidebar" id="idm119424">
<h5>Reusing CSS Styles for Multiple Formats</h5>
<p>You can use <code>@import</code> rules within your theme repository, to make maintaining CSS styles easier. For example, if you want your EPUB and MOBI files to look exactly the same, you can import the EPUB stylesheet into the MOBI stylesheet, and then you only need to keep one CSS file up-to-date if you ever decide to make any changes.</p>
<p>When importing styles within your theme folder, use relative paths to point to the file you want to reuse. For example, you might do the following in your <code>mobi.css</code> file:</p>
<pre class="prettyprint" data-original-title="" title="">
@import url('../epub/epub.css');
@media amzn-mobi {
h1 {
font-size: 120%;
}
}
</pre>
</div></aside>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Styling for HTML Output"><div class="sect2" id="idm114672">
<h2>Styling for HTML Output</h2>
<p>Atlas comes with an option to export your project as a fully-functional website that you can upload to the server of your choice. When you build the project, you’ll receive a zip file of the project files, CSS, images, and any custom JavaScripts or other assets you’ve chosen to include, as discussed in <a data-type="xref" href="ch06.html#javascripts">“Including Custom JavaScripts”</a>.</p>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>To learn more about the different build options for exporting your project as a website, read <a data-type="xref" href="ch06.html#building">Chapter 6</a></p>
</div>
<p>Writing CSS for HTML output is fairly straightforward--just style things as you would for the Web. We encourage you to consider including navigation elements, a header, and other standard website features to your HTML theme, so that the end result is a fully-functional, beautiful website.</p>
<section data-type="sect3" data-pdf-bookmark="The HTML layout file"><div class="sect3" id="htmllayout">
<h3>The HTML layout file</h3>
<p>In order to make a functional website, each file that you create in Atlas gets wrapped in layout file, that adds header information, links to JavaScripts and CSS files, and standard HTML wrapper tags. All Atlas projects will use a default layout.html file, but you can also create a custom layout file for your theme, for example if you want to add a top navigation bar, or extra navigation links before or after the book content.</p>
<p>If you choose to create your own layout file, simply create a file called <code>layout.html</code>, and save it in the <code>html</code> folder in your theme repo alongside your <code>html.css</code> file. Your <code>layout.html</code> file must include some standard elements in order for it to work correctly with Atlas, but you can add any extra stuff in addition to those required elements.</p>
<div data-type="note" epub:type="note">
<h1>Note</h1>
<p>Remember that anything you add to the layout.html file will appear on <em>every</em> page of your project website.</p>
</div>
<p>Here’s the boilerplate stuff that needs to be in any layout.html file:</p>
<pre class="prettyprint" data-original-title="" title="">
{{ doctype }}
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>{{ title }}</title>
{{ header }}
</head>
<body data-type="book">
{{ content }}
</body>
</html></pre>
<p>You can see in the above code block that Atlas <code>layout.html</code> files use a mix of variables and HTML. Read up on variables in <a href="#">Includes</a>. To see an example of a customized layout.html file, check out the <a href="https://github.com/oreillymedia/atlas_trade_theme/blob/master/html/layout.html">Atlas Trade Theme</a>.</p>
</div></section>
</div></section>
</div></section>
<section data-type="sect1" data-pdf-bookmark="Customizing Your Project Styles"><div class="sect1" id="csscustomizations">
<h1>Customizing Your Project Styles</h1>
<p>Sometimes you don’t need or want to create a whole new theme—you may want to keep most of the design the same, but have the text flow in 2 columns in the PDF instead of 1, or add a custom style for special boxes that you’re adding to your book that aren’t part of one of the available themes. By using our override architecture, you can customize your project design without needing to define styles for every single element.</p>
<p>Every Atlas project includes a <code>theme</code> folder, where you can add custom CSS to override the theme styles, or to create new styles for custom elements you want to add just to your project.</p>
<section data-type="sect2" data-pdf-bookmark="How to Do It"><div class="sect2" id="idm94176">
<h2>How to Do It</h2>
<p>The Build system looks for CSS overrides in a <code>theme</code> folder within your project repository. The structure of the theme folder should look just like the structure of an actual theme:</p>
<figure><div class="figure"><img class="iassetsimagestheme-01png" src="assets/theme-01.png"/>
<h6><span class="label">Figure 7-2. </span>File structure for theme overrides within a single project.</h6>
</div></figure>
<p>All of these files are optional--you only need to include them if you want to add custom styles or overrides for each format. You can also add a custom <code>layout.html</code> file just for your project, if you’re exporting it for the Web. Read about HTML layout files above (see <a data-original-title="" data-type="xref" title="" href="#htmllayout">“The HTML layout file”</a>).</p>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Advanced Styling for HTML Output"><div class="sect2" id="idm87760">
<h2>Advanced Styling for HTML Output</h2>
<p>The HTML format offers more opportunity for interaction and styling over PDF and other ebook formats. When building for HTML output, you may specify other stylesheets in the <code>atlas.json</code> file as well as custom javascripts to be included in the <code>head</code> of every page. More documentation these settings can be found in the <a data-type="xref" href="ch08.html#html-format-options">???</a>.</p>
</div></section>
<p> </p>
</div></section>
</div></section></body></html>