Vivliostyle CSS Typesetting

Table of Contents

Vivliostyle Viewer User’s Guide

Vivliostyle Viewer is a web application displaying and typesetting HTML+CSS documents.

How to use

To use the Vivliostyle Viewer in a local environment, start a web server by following the instructions described in the README.md (read online) attached to the distribution package.

You can also use the public online Vivliostyle Viewer, https://vivliostyle.github.io/vivliostyle.js/viewer/vivliostyle-viewer.html, that has always been updated to the latest development version.

The vivliostyle-viewer.html in the viewer folder is the main file of Vivliostyle Viewer.

When you open Vivliostyle Viewer without specifying parameters, an “Input a document URL” box and the following usage description is displayed:

Supported document types:

• (X)HTML document, with CSS for paged media
• Web publication (a collection of HTML documents): specify URL of the primary entry page or manifest file.
• Unzipped EPUB: specify URL of OPF file or top directory of the unzipped EPUB files.

Notes:

• GitHub and Gist URLs can be directly specified. Vivliostyle loads raw github/gist content when such URL is specified.
• ⚠️Mixed Content (“http:” URL is specified to “https:” Vivliostyle Viewer) is usually blocked by browser.
• ⚠️Cross-Origin (request to different domain) is usually blocked by browser unless the server is configured to allow Cross-Origin Resource Sharing (CORS).

URL parameter options:

• #b=<document URL> or #x=<document URL>
  • #b= Book view. When (X)HTML document URL is specified, the URL is treated as primary entry page’s, and a series of HTML documents linked from the manifest or TOC (Table of Contents, e.g. marked up with <nav role="doc-toc">) are automatically loaded.
  • #x= (X)HTML document is simply loaded. Multiple documents can be specified as #x=<1st HTML>&x=<2nd HTML>...
• &spread=[true | false | auto]
  • true: Spread view
  • false: Single page view
  • auto: Auto spread view (default)
• &renderAllPages=[true | false]
  • true: for Print (all pages printable, page count works as expected)
  • false: for Read (quick loading with rough page count)
• &style=<additional external style sheet URL>
• &userStyle=<user style sheet URL>

Options can also be set in the Settings panel.

Specifying HTML documents to be displayed in Vivliostyle Viewer

To display an HTML file in the Vivliostyle Viewer, place the file (and CSS or image files read from the file) somewhere which the web server can read (if you start the web server following the above instructions in case of local environment, it is the folder generated by unzipping the distribution package), then open the following URL in your browser:

Note: If you want to display a document from a domain which is different from the domain of the Vivliostyle Viewer itself, it is possible that it cannot be displayed, depending on the web server that serves the document file. You need to configure CORS (Cross-Origin Resource Sharing) on the server.

Note: Since Vivliostyle Viewer uses an online JavaScript library (MathJax) to display mathematics (supports MathML and TeX formats), the internet connection is required when the document contains mathematics.

Example: If you want to display a HTML file samples/wood/index.html:

Input the document file path (or URL) in the text box; the Vivliostyle Viewer URL of the document is displayed below:

To display EPUB

You can display unzipped EPUB files with the Vivliostyle Viewer. In this case, use the following parameter:

Example: If you want to display an unzipped EPUB folder samples/niimi/:

Input the EPUB folder path (or URL) in the text box; the Vivliostyle Viewer URL of the EPUB document is displayed below:

An example of displaying unzipped EPUB on GitHub:

• Accessible EPUB 3 on IDPF/epub3-samples
  http://localhost:8000/viewer/vivliostyle-viewer.html#b=https://github.com/IDPF/epub3-samples/tree/master/30/accessible_epub_3/

To display Web publications

You can display Web publications (a collection of HTML documents) with the Vivliostyle Viewer. In this case, use the following parameter:

For the format of Web publication manifest, W3C draft Web Publications and Readium Web Publication Manifest are supported.

When Web publication manifest does not exist, and there are links to other HTML documents in the table of contents in the specified HTML document, those documents are loaded automatically. Vivliostyle treats HTML elements that match the following CSS selector as a table of contents element: [role=doc-toc], [role=directory], nav li, .toc, #toc

An example of displaying publications composed of multiple HTML documents published on the Web:

• Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification on CSS Working Group Editor Drafts
  http://localhost:8000/viewer/vivliostyle-viewer.html#b=https://drafts.csswg.org/css2/

To specify page spread view mode

Vivliostyle Viewer displays pages automatically with spread view mode when the width of the view area is wide (1.45 times the height or more). To change the spread view mode, append one of the following to the URL:

You can also change the page view mode in the Vivliostyle Viewer's setting panel (open by clicking the icon in the upper right corner of the viewer).

To specify additional style sheets

To use additional style sheets (CSS files) in addition to the style sheets specified in the HTML file, append the following to the URL:

The style sheets specified in this way are treated as author style sheets, as if they are specified in the HTML file at very last, and can override styles of other style sheets according to the CSS cascading rules.

On the other hand, you can also specify user style sheets (cannot override styles of author style sheets unless specifying !important) as follows:

Using multiple &style= and/or &userStyle= you can specify as many style sheets as needed.

You can also use data URL. For example:

User style can also be set in the User Style Preferences in the settings panel. You can check the CSS in the CSS Details box.

An example in which user style settings are added from the settings panel to the document on the Web:

• Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification on CSS Working Group Editor Drafts
  http://localhost:8000/viewer/vivliostyle-viewer.html#b=https://drafts.csswg.org/css2/&userStyle=data:,/*%3Cviewer%3E*/%0A@page%20%7B%20size:%20A4;%20%7D%0A/*%3C/viewer%3E*/%0A%0A@page%20:first%20%7B%0A%20%20@top-left%20%7B%0A%20%20%20%20content:%20none;%0A%20%20%7D%0A%20%20@top-right%20%7B%0A%20%20%20%20content:%20none;%0A%20%20%7D%0A%20%20@bottom-center%20%7B%0A%20%20%20%20content:%20none;%0A%20%20%7D%0A%7D%0A%0A@page%20:left%20%7B%0A%20%20font-size:%200.8rem;%0A%20%20@top-left%20%7B%0A%20%20%20%20content:%20env(pub-title);%0A%20%20%7D%0A%20%20@bottom-center%20%7B%0A%20%20%20%20content:%20counter(page);%0A%20%20%7D%0A%7D%0A%0A@page%20:right%20%7B%0A%20%20font-size:%200.8rem;%0A%20%20@top-right%20%7B%0A%20%20%20%20content:%20env(doc-title);%0A%20%20%7D%0A%20%20@bottom-center%20%7B%0A%20%20%20%20content:%20counter(page);%0A%20%20%7D%0A%7D&renderAllPages=true

When setting styles from the settings panel like this example, the CSS code of the styles set from option items in the settings panel is generated between the comments /*<viewer>*/ and /*</viewer>*/ in the user style CSS that are displayed in the CSS Details box. You can add your own CSS code to it. In this example, page header and footer are added.

How to Print/Save as PDF from Vivliostyle Viewer

Use your browser’s print/save as PDF feature. For example, to save as PDF with Google Chrome, select Print from menu, set Destination to “Save as PDF”, check “Background graphics”, and “Save” to PDF.

Note: When you print all pages of a document, check that Render All Pages is On in the setting panel. When this is Off, only the pages that have already been displayed can be printed, and the page number will not be output correctly.

CSS features supported by Vivliostyle

Supported CSS features are described in Features supported by Vivliostyle.

Other documentation

You can find other documentation at Vivliostyle Documentation

Samples

• Page/Spread View for auto spread paginated view with online Vivliostyle Viewer.
• Page View for single page paginated view with online Vivliostyle Viewer.
• Spread View for spread paginated view with online Vivliostyle Viewer.
• Raw HTML for normal HTML view.
• Source for source files, HTML+CSS etc., on GitHub.

Other samples

You can find other samples at Vivliostyle Samples.