For most books, the default outputs (
app) are sufficient. You only need one version of each of those. But sometimes you need a variation on one or more of these. For instance, you might be producing two versions of a printed book with different designs (e.g. for schools and for trade) with different selections of chapters. Or you may be white-labelling a website, and need to output various versions with different colours or logos. Variants make that possible.
Activating a variant
To activate a variant, put its name as the
settings.yml. Make sure you deactivate it, for instance by commenting it out, to get your default output back.
You can create new stylesheets in addition to our standard ones, and specify these in
_data/settings.yml file, like this:
variants: - variant: myvariant print-pdf-stylesheet: "print-pdf-myvariant.css" web-stylesheet: "web-myvariant.css" - variant: anothervariant app-variant-stylesheet: "app-anothervariant.css"
You can define variant-specific metadata in
_data/meta.yml in the same way you’d create metadata for a translation, by creating a
variants node in a
work containing all the same metadata you would for the
work. Except instead of setting a
directory, you set a
variant, which matches the name of the variant you created in
settings.yml. This can include things like
files lists, and
nav nodes. For example:
variants: - variant: myvariant identifier: "9781234567890" products: epub: identifier: "9780987654321"
Variant tables of contents
For TOCs, you can also change the TOC output for a variant by adding the names of the variants in which a TOC item should appear to the main book’s TOC
item node as
variants. This makes sure that that node in the TOC only outputs when outputting one of the listed variants. For example:
toc: label: "Study tips" file: "05-study-tips" variants: school, varsity
active-variant is defined in
_data/settings, and the default
nav are output, any items that do not include the
active-variant’s name in its
variants list will not be output.
This can be much easier to maintain than creating a whole new
toc node to the variant’s metadata, which would mostly be a straight duplication of the default output.