Output Your Project

Quire is designed to create a website version, a PDF version and two e-book versions of your project from the same source files. Each can be customized in various ways as described below. Once your outputs are ready, visit the Deploy Your Project section of our documentation to learn how to deploy your project to the web.

Site Output

Create the HTML files for your project by running quire site in your command-line shell. The files will be built into your project’s site folder along with all the necessary static assets like image files, stylesheets and script files. The site file will be updated and overwritten each time you run quire site.

You can hide specific pages of your project from the site output by adding online: false to the page YAML. Or conversely, you can add pages exclusively to the site output, by adding epub: false and pdf: false to the page YAML and leaving the online attribute unset, or set to true.

Unlike epub: false and pdf: false, adding online: false does not stop a page from being built and included in the site output. Rather, it just unlinks those pages and adds a metadata tag to them to prevent them from being indexed by search engines. You may want to manually delete the pages from the site folder after outputting and before uploading to a web server if you want to be fully certain they can’t be accessed online under any circumstances.

E-Book Output

Quire can output two different reflowable e-book formats: EPUB and MOBI. EPUB is the most widely used format and will work on most devices and for most e-book vendors. EPUB is an official specification of the World Wide Web Consortium (W3C), and Quire outputs the latest version: EPUB 3.2.

Very closely related to EPUB, the MOBI format is used almost exclusively by Amazon’s Kindle. Making it available in your project will allow Kindle readers to load the e-book onto their devices directly. (Amazon itself asks for EPUBs when selling/distributing through them, which it then converts to MOBI and other proprietary formats as needed.)

The MOBI file is derived directly from the EPUB version of your project, and does not have styling or customization options separate from the EPUB.

You can remove specific pages of your project from the e-book outputs by adding epub: false to the page YAML. Or conversely, you can add pages exclusively to the e-book outputs, by adding online: false and pdf: false to the page YAML and leaving the epub attribute unset, or set to true.

For developers creating custom templates, you can use templating logic to create specific outputs for the e-books by querying if eq .Site.Data.params.epub true. This parameter is set in the config/epub.yml file.

Create and View the E-Book Files

Create an EPUB of your project by running quire epub in your command-line shell. An output.epub file will be created and saved to your project’s static/downloads/ folder. This file will be updated and overwritten each time you run quire epub.

Create a MOBI of your project by running quire mobi in your command-line shell. An output.mobi file will be created and saved to your project’s static/downloads/ folder. This file will be updated and overwritten each time you run quire mobi.

EPUB files can be viewed on the default Books app on macOS, or on a number of free EPUB readers available for both Windows and Mac.

MOBI files can be viewed with Kindle Previewer on both Windows and Mac.

EPUBCheck Validation

If you will be distributing your EPUB file via e-book vendors/distributors, it will have to pass validation with EPUBCheck. EPUBCheck verifies that the file conforms to EPUB standards which ensures that it will work properly across devices. A valid EPUB will also ensure a valid MOBI file.

Quire’s default output will pass EPUBCheck, but the EPUB standard is very strict and a number of things can lead to an invalid file. By far the most common errors are broken internal links in markdown files to other files or to heading or image anchors within the file.

While there is an online validator for smaller files (10MB or less) we recommend downloading EPUBCheck and using it directly.

1. Download and install Java from https://www.java.com/.
2. Download the ZIP file of the latest EPUBCheck release from https://github.com/w3c/epubcheck/releases.
3. Unzip the downloaded folder. Inside it is a epubcheck.jar file that you’ll reference in the next step.
4. In Terminal or PowerShell Admin type: java -jar path-to-epubcheck.jar path-to-output.epub

EPUBCheck will output a list of any errors or warnings that exist in your file. Only the errors need to be addressed for the file to be considered valid by most e-book vendors. Warnings are optional. Errors will be referenced by filename and line number. The filenames will be internal EPUB naming and not correspond to anything in your markdown project files. See the tip below for looking inside the EPUB file to track down the source of these listed errors.

EPUB Styles

EPUBs in Quire have their own style sheet separate from any styles applied to the online version of your project. EPUB styles can be modified and added to in the themes/default/source/css/epub.scss file.

Quire uses Pandoc to create the EPUB files, and while consistent in outputting valid EPUB files, Pandoc also strips out a lot of the class names and other structures you may normally use to add custom styling. See the tip above for looking into the EPUB file, and use that to find class names and HTML structures as Pandoc outputs them for use as selectors in your CSS.

PDF/Print Output

Create a PDF of your project by running quire pdf in your command-line shell. An output.pdf file will be created and saved to your project’s static/downloads/ folder. This file will be updated and overwritten each time you run quire pdf.

By default, the PDF is output at full-resolution and with crop marks for professional printing. You may want to manually crop the pages and downsample the file to a smaller file size using a program like Adobe Acrobat if you are only making it available as a digital download.

Quire’s PDF output is generated by PrinceXML which you should have installed when first installing Quire. PrinceXML is free to download for non-commercial use, though it does add a logo watermark to the first page of the PDF ouput. A desktop license can be purchased that will remove the watermark and also allow for commercial use.

You can remove specific pages of your project from the PDF output by adding pdf: false to the page YAML. Or conversely, you can add pages exclusively to the PDF output, by adding online: false and epub: false to the page YAML and leaving the pdf attribute unset, or set to true.

For developers creating custom templates, you can use templating logic to create specific outputs for the PDF by querying if eq .Site.Data.params.pdf true. This parameter is set in the config/pdf.yml file.

Modifying and Styling the PDF

PrinceXML creates the PDF from the website version of your Quire site using CSS rules. You can modify Quire’s PDF styles using CSS just like you would modify Quire’s online styles. You can read more about styles in general in the Style Customization section of this guide.

There are a number of CSS variables defined in Quire that allow you to adjust various parts of the PDF output, including the page size. The default page size is 8.5 × 11 inches.

In the themes/default/source/css/variable.scss file, are a number of key print/PDF-related variables:

// Print/PDF stylesheet
// -----------------------------------------------------------------------------
$print-width: 8.5in;
$print-height: 11in;
$print-bleed: .125in;

$print-base-font-size: 8.5pt;
$print-text-color: $black;

$print-splash-color: $off-white;

$print-entry-image-color: $rich-black;
$print-entry-caption-color: $white;
$print-entry-image-display: all; // first | all

There are even more PDF-related variables that can be modified in the source/css/print.scss file. Including page margins, and rules regarding the running feet and page numbering that are included at the bottom of each PDF page.

Where a variable is not available, you can also add custom CSS to your static/css/custom.css file to achieve the desired result. You can target changes to only the print output by wrapping your CSS rules in a media query.

For example, this would hide all video elements in the print output:

@media print {
  video {
    display: none;
  }
}

Some of the CSS used in styling the PDF is from the CSS Paged Media Specification. This is a set of CSS rules designed specifically to style things in a page-like manner, including controlling left and right page rules, page numbering, and running feet and heads. There is good information about this in PrinceXML’s documentation.

Tips for PDF Design and Development

For developers and designers interested in making more extensive changes to the PDF output, you can make the process easier by using a PDF reader that will autoreload, and displaying a version of the PDF output in your browser.

When working on improving or modifying the styling of your PDF output, the basic methodology is to output the PDF with quire pdf, open it, look at what you want to change, write/modify your CSS accordingly, run quire pdf again, open it, look to see if the CSS change had the desired effect, rinse and repeat. It is, in a word, cumbersome. But there are some things that will make this process a little easier.

Use an Auto-Reloading PDF Reader

Adobe Acrobat (a popular PDF reader) won’t reload the PDF you’re looking at if the file has been changed. We recommend instead using a PDF reader, like Skim for macOS, that will reload the PDF every time it’s changed. For Quire development, this means you can open the PDF to a page you want to make a style change to, make the change in your project, run quire pdf and see that change happen as soon as the PDF process is finished running. It takes away the wasted time of closing PDFs, opening new versions and finding your place in them time and time again.

Display the PDF Version in a Browser

You can use your browser to display a decent, though not exact, preview of what the print output will be. It won’t have the correct page sizes or margins and page numbering, but you’ll see the overall text sizes and styles, figures, spacing between these elements, and other parts generally as they’ll look in the PDF. This means that you can make changes to your CSS and see a live preview in the browser without having to output the PDF every time.

1. Open the config.yml file and at the bottom of the list of params temporarily add pdf: true, which tells Quire to build the PDF version of your site. Be sure to delete this line when you’re done working on the PDF.

2. Open your site preview in Firefox or Chrome, it will look a little different and some elements may be missing or altered.

3. Right or Control-Click anywhere on the preview:

   Firefox: Select Inspect Element and then click the small page icon in the upper right of the window that opens. (On hover, the icon will say “Toggle print media simulation for the page”.)

   Chrome: Select Inspect, click the three-dots menu icon in the upper right of the window that opens, select More Tools, and then Rendering. In the area that opens, scroll down to “Emulate CSS media type” and select “print”.

You can also use the web inspector to help track down different HTML elements and CSS selectors that are effecting the final PDF output. This can make it easier to make changes that will have the desired effect.