Customisable book designs created with paged.js
.
This project is a work in progress. The aim is to make it easy to create and adapt book designs for use with paged.js
.
Our default library of Sass partials account for common book features as base styles (e.g. _bibliography.scss
). These partials have a vanilla, non-opinionated design, and can be styled lightly just by setting Sass variables.
Our default styles follow common book-design fundamentals, such as indented paragraphs, running heads, copyright-page layouts, and start-on-recto pages.
The project already includes a few opinionated designs as themes. You can use or adapt them to suit your books.
If your HTML happens to use the same structure and selectors as our defaults, you can use one of our CSS stylesheets as is.
- Copy a CSS file from one of the theme folders in
css/themes/
, and link to it in your book's HTML files. - Link to the
paged.js
script.
So, this means your HTML head
will include these two tags:
<link rel="stylesheet" type="text/css" href="path/to/main.css">
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
- Install Node.
- Clone this repo.
- At the command line in this folder, run
npm install
. - To run the site locally and build CSS as you make changes, run
npm start
and open Chrome at http://localhost:5000.
-
In
themes
, make a copy ofthemes/template
or another theme you want to adapt. -
Edit and add to your theme's
_selectors.scss
,_styles.scss
, and_variables.scss
. These simply override the defaults when they're imported by the theme'smain.scss
file. See Creating new styles below for more detail. -
Add your theme to the
themes
inindex.js
and injs/pager.js
. -
To run the site locally and build CSS as you make changes, run
npm start
at the command line. Open Chrome at http://localhost:5000.This builds and watches for Sass changes, and serves
index.html
so that the page can fetchpaged.js
over HTTP.
Note that in order to demo stylesheets in this project, we load stylesheets and paged.js
with js/pager.js
. Our pager.js
script adds the theme selector and waits for any MathJax to load on the page. In your finished books, you wouldn't do this. You'd most likely just add this to your HTML head
:
<link rel="stylesheet" type="text/css" href="path/to/main.css">
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
This repo contains:
content/
: sample books and book parts that usepaged.js
.default/
: the base styles that all stylesheets share.default/partials/
: a set of Sass partials. Default styles all start here.default/main.scss
: the file that imports variables and partials.default/_selectors.scss
: defines which HTML elements you use for common book features.default/_styles.scss
: defines (or imports) styles that apply to those elements.default/_variables.scss
: defines a wide range of variables that affect your book design.
themes/
: opinionated variations on thedefault
styles, where you can create custom themes by defining your own selectors, variables and styles. Each theme subfolder follows the same structure asdefault/
.css/
: the output folder, where finished CSS lands.index.js
: the Node script that builds CSS from Sass and watches for changes there.LICENSE
: a CC0 license.README.md
: this guidance.index.html
: a landing page for the sample content in this repo.
And a few other files for the build tools.
Our aim is to make it quicker and easier to create new book designs, without writing loads of CSS from scratch.
There are three optional steps to creating a new theme:
-
Add your book's selectors in
themes/yourtheme/_selectors.scss
.Depending how your books' HTML has been built, you may have different selectors for book features. For instance, a chapter in one book might be in
<div class="chapter">
, and<section id="chapter-1">
in another. The different chapter selectors in each of these cases might be.chapter
and[id^=chapter-]
respectively. -
Set variables in
themes/yourtheme/_variables.scss
.We use a bunch of variables that affect your final CSS. You can see the defaults in
default/_variables.scss
. To override one of those, add it tothemes/yourtheme/_variables.scss
without the!default
rule. For example, to change the page width, add$page-width: 152mm;
tothemes/yourtheme/_variables.scss
. -
Add your own style rules to
themes/yourtheme/_styles.scss
.This file is for any styling. You can write in CSS or
.scss
syntax. To keep your designs aesthetically consistent, it's good to be familiar with the variables we design with indefault/_variables.scss
, and to use them wherever possible.
We create many book features as Sass mixins, which are then @include
d in elements and classes.
This makes it easy to give different elements the same design in different contexts. For example, let's say your book's chapters are divided into parts. Your part titles will be h1
s, and your chapter titles h2
s. What heading level are your frontmatter headings, like 'Contents' and 'Prologue'? They are h1
s sementically, but in terms of visual significance they need to look like the h2
s.
So if, visually speaking, you have a big heading-1
and a smaller heading-2
, your part titles need to be h1.heading-1
, your frontmatter titles h1.heading-2
, and your chapter titles h2.heading-2
. This will ensure you have both semantically accurate HTML and visually sensible styles.
For that reason, we've created styles as mixins, which can then be applied to any given element or class in your custom CSS. For example, if you want a p.subheadline
paragraph to look like an h2
, but remain a paragraph in HTML, you'd add this to your custom CSS:
.subheadline {
@include heading-2();
}
And if you want your dedications to look like epigraphs:
.dedication {
@include epigraph();
}
Some existing roadmap items and issues in paged.js
that are relevant here:
- We can't yet reset a page number to a specific number, e.g.
.page-20 (counter-reset: page 20)}
only resets to 1, not to 20. (See issue 91.) - We can't yet
float: top
andfloat: bottom
. (See issue 90.) - Bleed and trim are not yet supported. (See issue 82.)
- Setting a
leader(" ")
ina::after
for TOCs is not yet supported. This is noted on the specs roadmap. - We can't use
string-set
yet. (See issue 44.)
When writing CSS, also note that the divs that paged.js
introduces (in order to manage pagination) break some CSS child selectors like >
. This is probably not avoidable, but it does make design work more challenging, and is important to keep in mind.
In this project, we link to online web fonts. This is just for demo purposes, and is a bad idea for real book production. When you make books for production, you should save and link to the actual font files in each project, and not link to fonts on the web, or to font files shared by different projects. This is because once you've refined your pages, any changes to the font files (e.g. adjustments to glyphs or kerning) could cause your pages to reflow in new and unintended ways.