Themes and CSS

To add styling such as fonts and text sizes to your manuscript, apply a Cascading Style Sheet (CSS), similar to how you would with an HTML file.

Adding Additional Stylesheets

To use additional stylesheets (CSS files) alongside those specified in the HTML file, use the --style option.

vivliostyle build example.html --style additional-style.css

The stylesheet specified this way will be treated the same as the author stylesheet specified in the HTML file. Since it is specified later, it will override the styles in the HTML file according to CSS cascading rules.

Specifying User Stylesheets

To use a user stylesheet, specify the stylesheet with the --user-style option. User stylesheets do not override author stylesheets unless the style is specified with !important.

vivliostyle build example.html --user-style user-style.css

Specifying CSS Content Directly

By using the --css option, you can pass the stylesheet directly as CSS text. This option is useful for setting simple stylesheets or CSS variables.

vivliostyle build example.html --css "body { background-color: lime; }"

Specifying Page Size

You can specify the page size with the -s (--size) option. The sizes you can specify are A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger, or you can specify the width and height separated by a comma.

vivliostyle build paper.html -s A4 -o paper.pdf
vivliostyle build letter.html -s letter -o letter.pdf
vivliostyle build slide.html -s 10in,7.5in -o slide.pdf

This option is equivalent to --css "@page { size: <size>; }".

Specifying Crop Marks

By using the -m (--crop-marks) option, crop marks (indicators of the cutting position for printed materials) will be added to the output PDF.

vivliostyle build example.html -m

You can specify the bleed width when adding crop marks with the --bleed option. You can also specify the width outside the crop marks with the --crop-offset option.

vivliostyle build example.html -m --bleed 5mm
vivliostyle build example.html -m --crop-offset 20mm

This option is equivalent to --css "@page { marks: crop cross; bleed: <bleed>; crop-offset: <crop-offset>; }".

About Vivliostyle Themes

Vivliostyle Themes

Vivliostyle Themes is an official collection of style themes used when creating publications with Vivliostyle. By referring to Vivliostyle Themes, you can apply styles without preparing your own CSS.

Finding Themes

To find themes published as npm packages, search for the keyword "vivliostyle-theme" on npm:

List of Themes (npm)

Using Themes

You can use a theme by specifying the -T (--theme) option or theme in the configuration file. If the theme file does not exist locally, it will be automatically installed on the first run.

vivliostyle build manuscript.md --theme @vivliostyle/theme-techbook -o paper.pdf

You can also use themes available in your local environment. If it is a single CSS file, you can specify the CSS file directly as follows.

vivliostyle build manuscript.md --theme ./my-theme/style.css -o paper.pdf

If there is a package.json file that conforms to npm in your local environment, you can also load the Vivliostyle Theme in that directory. The following is an example where a package available as a Vivliostyle Theme is placed in the my-theme directory.

vivliostyle build manuscript.md --theme ./my-theme -o paper.pdf

All of the settings above can be specified in the configuration file, and you can also use more than one of them.

theme: [
  '@vivliostyle/theme-techbook',
  './my-theme',
],

Importing Themes from CSS

Instead of specifying Vivliostyle Themes with the theme option, you can import a theme package directly with its npm package name, from a CSS file specified with the theme option:

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

h1 {
  /* your customization */
}

An import with the package name alone loads the default style entry of the package, resolved from the vivliostyle.theme.style, style, exports (with the style condition), and main fields of its package.json, in this order. An import with a subpath loads the specified file; when the package declares the exports field, the subpath is resolved through it.

The imported packages are automatically installed, in the same way as the themes specified with the theme option. A specifier can also request the version to install, with the npm-style @ notation after the package name:

@import '@vivliostyle/theme-base@^3.0.0';

A specifier is treated as a relative URL and keeps the standard CSS semantics when it points to an existing file with the .css extension; for example, @import 'foo.css' refers to the relative file when it exists next to the importing stylesheet. Any other specifier is resolved as an npm package. When the same package is installed both in the project and in the themes directory, the one in the themes directory takes precedence.

Using Create Book

By using Create Book, you can easily create a project with a theme already set. Refer to Creating a Vivliostyle Project.

Using PostCSS

If your project has a PostCSS configuration file, Vivliostyle CLI applies its plugins to every CSS file it processes.

Place the PostCSS config in the same directory as the configuration file. Any config format supported by postcss-load-config (e.g. postcss.config.js) can be loaded. The config is also applied to the CSS files of the theme packages you use.

The css.postcss option of the configuration file accepts an inline PostCSS config, or a directory to search for the PostCSS config file from. If an inline config is provided, the PostCSS config file is not searched.

import autoprefixer from 'autoprefixer';

export default {
  entry: ['manuscript.md'],
  css: {
    postcss: {
      plugins: [autoprefixer()],
    },
  },
};

Tailwind CSS

Example: with-tailwindcss

Through PostCSS plugins, you can also use CSS frameworks such as Tailwind CSS.

Follow the Using PostCSS section of the Tailwind CSS documentation to set it up.

Tailwind CSS is a framework that styles elements through classes called utility classes, applying the styles that correspond to each class name. When combined with VFM, you can specify the classes with the VFM attribute syntax as follows; Tailwind scans the manuscript files and generates the styles for the classes in use.

# Vivliostyle meets Tailwind CSS {.text-4xl .font-extrabold .tracking-tight .text-accent}

This document is styled with [Tailwind CSS](https://tailwindcss.com/) utility classes.
Tailwind scans this Markdown file for class names, so you can attach utilities to
inline elements with the **VFM attribute syntax**{.bg-accent/15 .px-1 .rounded} like
`**text**{.underline}`.

Tailwind CSS is a powerful tool, but the text-centric documents Vivliostyle mainly targets differ from web pages in many ways, and whether styling with utility classes fits your writing process depends on your authoring style. Still, it can be a strong option when you want plenty of ad hoc styles in your text.

Creating a Theme

You can create your own Vivliostyle Theme and publish it as an npm package so that other users can apply it to their publications.

Scaffolding a Theme Package

The vivliostyle theme create command scaffolds a new theme package. Answer the questions it asks, and the necessary files and directories are generated.

vivliostyle theme create

If Vivliostyle CLI is not installed, npm create vivliostyle-theme@latest runs the same command without installing it.

npm create vivliostyle-theme@latest
yarn create vivliostyle-theme # For yarn users
pnpm create vivliostyle-theme # For pnpm users

The generated package has the following structure:

my-theme/
├── README.md
├── example/
│   ├── assets/
│   ├── 01_typography.md
│   ├── 02_figures-and-tables.md
│   └── 03_code-and-math.md
├── package.json
├── theme.css
└── vivliostyle.config.js

theme.css: The stylesheet of the theme. It imports @vivliostyle/theme-base and its feature modules, and adjusts them with CSS variables.
example/: Sample manuscripts that cover the elements a theme should style, such as headings, lists, footnotes, figures, tables, code, and math. npm run example:preview opens a preview of them with the theme applied.
vivliostyle.config.js: The configuration used to preview and build the sample manuscripts.

Theme Metadata

A theme package describes itself in the vivliostyle.theme field of package.json. Vivliostyle CLI reads this field to locate the stylesheet. See the Vivliostyle Themes documentation for the details of each field.

{
  "name": "vivliostyle-theme-my-theme",
  "author": "John Doe <[email protected]>",
  "main": "theme.css",
  "keywords": ["vivliostyle", "vivliostyle-theme"],
  "vivliostyle": {
    "theme": {
      "name": "My Theme",
      "author": "John Doe",
      "style": "theme.css",
      "category": "novel",
      "topics": ["paperback"]
    }
  }
}

A theme package can also provide project templates. See Providing Templates in a Vivliostyle Themes Package.

Validating a Theme Package

The vivliostyle theme validate command checks that a theme package is set up correctly. Run it in the theme directory, or pass the path to the directory as an argument.

vivliostyle theme validate

It validates the schema of the vivliostyle field and reports the following:

Error: The style file is not specified, or the specified file does not exist inside the package.
Warning: The author is not specified.
Warning: keywords does not include vivliostyle-theme.
Warning: vivliostyle.theme.category is not one of the known categories.

The command exits with a non-zero status when any error is reported, so it can be used in a prepublishOnly script or in CI. The generated package includes a validate script that runs this command.

Publishing a Theme

When the theme is ready, publish it to npm with npm publish. Published themes with the vivliostyle-theme keyword appear in the list of themes on npm and can be chosen with the create command. See the Vivliostyle Themes repository for the theme specification and how to contribute your theme to the official collection.