themes

Using Themes

Vivliostyle Theme is a style theme used for creating publications with Vivliostyle. Distributed as npm packages, themes can be applied to your publications simply by specifying them in vivliostyle.config.js.

Installing a Theme

Install the desired theme via npm.

npm install @vivliostyle/theme-techbook

Specifying a Theme

Basic Usage

Set the package name in the theme property of vivliostyle.config.js.

module.exports = {
  theme: '@vivliostyle/theme-techbook',
};

Specifying a Particular CSS File

Some themes provide multiple CSS files. To use a CSS file other than the default, specify specifier and import.

module.exports = {
  theme: {
    specifier: '@vivliostyle/theme-gutenberg',
    import: 'alice.css',
  },
};

Combining Multiple Themes

By passing an array to the theme property, you can combine multiple themes. For example, to change the code block color scheme of a theme:

module.exports = {
  theme: [
    '@vivliostyle/theme-techbook',
    {
      specifier: '@vivliostyle/theme-base',
      import: 'prism/theme-prism',
    },
  ],
};

Customizing with CSS Variables

Each theme exposes configuration values as CSS custom properties (CSS variables). You can adjust the theme’s styles by overriding these variables in a custom CSS file.

CSS Variable Naming Convention

Prefix	Purpose	Examples
`--vs-`	Meta properties affecting the entire document	`--vs-font-family`, `--vs-font-size`
`--vs--`	Styles for basic HTML tags	`--vs--heading-line-height`, `--vs--h1-font-size`
`--vs-{module}--`	Module-specific settings	`--vs-footnote--call-content`, `--vs-toc--ol-indent-size`
`--vs-theme-{name}--`	Theme-specific settings	`--vs-theme-techbook--inline-code-color-bg`, `--vs-theme-slide--cover-page-color-bg`

Customization Example

Create a custom CSS file that overrides the theme’s CSS variables, then add it in vivliostyle.config.js.

custom.css:

:root {
  --vs--anchor-text-color: #e74c3c;
  --vs-theme-techbook--inline-code-color-bg: #fdebd0;
  --vs-page--mbox-top-outside-content: 'My Book Title';
  --vs-page--mbox-bottom-outside-content: counter(page);
}

vivliostyle.config.js:

module.exports = {
  theme: [
    '@vivliostyle/theme-techbook',
    'custom.css',
  ],
};

Refer to each theme’s README for a complete list of available CSS variables.

Official Themes

@vivliostyle/theme-bunko

Suitable for Japanese vertical novels (bunko). Supports ruby and horizontal-in-vertical text. Configurable lines/characters per page.

Theme-bunko sample image. The manuscript is 'Night on the Galactic Railroad'.

@vivliostyle/theme-slide

Suitable for slide presentations. Supports cover page (.cover) and full-page image layouts.

Theme-slide sample image. On the left is the cover page with a blue background, and on the right is the general page with a white background.

@vivliostyle/theme-techbook

Suitable for technical books. Supports margin adjustment, table of contents, and source code highlighting.

Sample images from theme-techbook. In addition to text, it has a table and source code.

@vivliostyle/theme-academic

Suitable for reports and academic papers. Automatic chapter/section numbering and frame elements (.frame) are supported.

Sample images from theme-academic. In addition to text, it contains diagrams and tables.

@vivliostyle/theme-gutenberg

Suitable for English books. Three CSS variations available: alice.css, fang.css, sherlock.css.

Sample image from theme-gutenberg. The manuscript is 'Alice's Adventures in Wonderland'.

@vivliostyle/theme-epub3j

Suitable for Japanese EPUB 3 publications. Compatible with the EBPAJ EPUB 3 File Creation Guide.

Screenshot of theme-epub3j example.

@vivliostyle/theme-base

The CSS toolkit that serves as the foundation for other themes. Individual modules can be @imported as needed.

Sample image from theme-base.

See the Vivliostyle Themes Gallery for more details on each theme.

Using theme-base Directly

@vivliostyle/theme-base is the foundation for other themes. It can also be used as a toolkit for building custom themes.

Package Entry and Modules

The package entry (theme.css) contains only the basic modules: the CSS reset, the variable defaults, and basic styling. Every other module (cross-references, footnotes, page layout, TOC, etc.) is opt-in and imported through its own subpath such as @vivliostyle/theme-base/footnote.

// Using the basic modules
module.exports = {
  theme: '@vivliostyle/theme-base',
};

Available Modules

Module	Subpath	CSS Variable Prefix
Basic	(package entry)	`--vs-`, `--vs--`
Figures	`figure`	`--vs-figure--`
Tables	`table`	`--vs-table--`
Citations	`citation`	`--vs-citation--`
Code listings	`listing`	`--vs-listing--`
Equations	`equation`	`--vs-equation--`
Theorems	`theorem`	`--vs-theorem--`
Appendices	`appendix`	`--vs-appendix--`
Endnotes	`endnote`	`--vs-endnote--`
Footnotes	`footnote`	`--vs-footnote--`
Footnotes for external links	`footnote/external-links`	`--vs-footnote--`
Page layout	`page`	`--vs-page--`
Section references	`section`	`--vs-section--`
Table of Contents	`toc`	`--vs-toc--`
Math	`math`	`--vs-math--`
Sidenotes	`sidenote`	`--vs-sidenote--`
Prism (Code highlighting)	`prism`	`--vs-prism--`

Example of importing individual modules in CSS:

@import '@vivliostyle/theme-base';
@import '@vivliostyle/theme-base/toc';
@import '@vivliostyle/theme-base/footnote';

Importing by package name requires @vivliostyle/theme-base to be installed in your project (npm install @vivliostyle/theme-base). This form is available in Vivliostyle CLI v11.3.0 and later.

For detailed CSS variables of each module, see the theme-base README.

This site is open source. Improve this page.