日本語 | English
Config Reference

Config Reference

The configuration files vivliostyle.config.js and vivliostyle.config.json accept the VivliostyleConfigSchema for configuring the Vivliostyle CLI. You can reference the configuration's type scheme from TypeScript files.

import { VivliostyleConfigSchema } from '@vivliostyle/cli';

Alternatively, you can use the defineConfig helper function to define the configuration.

import { defineConfig } from '@vivliostyle/cli';

export default defineConfig({ ... });

Config API

VivliostyleConfigSchema

Type definition

type VivliostyleConfigSchema =
  | BuildTask[]
  | BuildTask;

BuildTask

Properties

  • BuildTask

    • entry: (string | ContentsEntryConfig | CoverEntryConfig | ArticleEntryConfig)[] | ArticleEntryConfig | string
      Entry file(s) of the document.

    • title: string
      Title of the document.

    • author: string
      Author of the document.

    • theme: (ThemeConfig | string)[] | ThemeConfig | string
      Theme package path(s) or URL(s) of the CSS file.

    • entryContext: string
      Directory containing the referenced entry file(s).

    • output: (OutputConfig | string)[] | OutputConfig | string
      Output options.

    • workspaceDir: string
      Directory where intermediate files (e.g., manuscript HTMLs, publication.json) are saved. (default: .vivliostyle)

    • includeAssets Deprecated
      Use copyAsset.includes instead.

    • copyAsset: CopyAssetConfig
      Options for asset files to be copied when exporting output.

    • size: string
      PDF output size. (default: letter)

      • Preset: A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger
      • Custom (comma-separated): 182mm,257mm or 8.5in,11in

    • pressReady Deprecated
      Use pdfPostprocess.preflight: "press-ready" instead

    • pdfPostprocess: PdfPostprocessConfig
      PDF post-processing options. When both pdfPostprocess and legacy options (pressReady, preflight, etc.) are specified, pdfPostprocess takes precedence.

    • language: string
      Language of the document.

    • readingProgression: "ltr" | "rtl"
      Specifies the reading progression of the document. This is typically determined automatically by the CSS writing-mode. Use this option only if explicit configuration is needed.

    • toc: TocConfig | boolean | string
      Options for Table of Contents (ToC) documents.

    • tocTitle Deprecated
      Use toc.title instead

    • cover: CoverConfig | string
      Options for cover images and cover page documents.

    • timeout: number
      Timeout limit for waiting for the Vivliostyle process (in ms). (default: 300000)

    • documentProcessor: (option: import("@vivliostyle/vfm").StringifyMarkdownOptions, metadata: import("@vivliostyle/vfm").Metadata) => import("unified").Processor
      Custom function to provide a unified Processor for converting the source document to HTML.

    • documentMetadataReader: (content: string) => import("@vivliostyle/vfm").Metadata
      Custom function to extract metadata from the source document content.

    • vfm: VfmConfig
      Options for converting Markdown into a stringified format (HTML).

    • image: string
      Docker image used for rendering.

    • http Deprecated
      This option is enabled by default, and the file protocol is no longer supported.

    • viewer: string
      URL of a custom viewer to display content instead of the default Vivliostyle CLI viewer. Useful for using a custom viewer with staging features (e.g., https://vivliostyle.vercel.app/).

    • viewerParam: string
      Parameters for the Vivliostyle viewer (e.g., allowScripts=false&pixelRatio=16).

    • browser: string
      Specify a browser type and version to launch the Vivliostyle viewer.

    • base: string
      Base path of the served documents. (default: /vivliostyle)

    • server: ServerConfig
      Options for the preview server.

    • static: [key: (string)]: (string)[] string
      Specifies static files to be served by the preview server. js export default { static: { '/static': 'path/to/static', '/': ['root1', 'root2'], }, };

    • temporaryFilePrefix: string
      Prefix for temporary file names.

    • vite: import("vite").UserConfig
      Configuration options for the Vite server.

    • viteConfigFile: string | boolean
      Path to the Vite config file. If a falsy value is provided, Vivliostyle CLI ignores the existing Vite config file.

Type definition

type BuildTask = {
  entry:
    | (
        | string
        | ContentsEntryConfig
        | CoverEntryConfig
        | ArticleEntryConfig
      )[]
    | ArticleEntryConfig
    | string;
  title?: string;
  author?: string;
  theme?:
    | (ThemeConfig | string)[]
    | ThemeConfig
    | string;
  entryContext?: string;
  output?:
    | (OutputConfig | string)[]
    | OutputConfig
    | string;
  workspaceDir?: string;
  includeAssets?: string[] | string;
  copyAsset?: CopyAssetConfig;
  size?: string;
  pressReady?: boolean;
  pdfPostprocess?: PdfPostprocessConfig;
  language?: string;
  readingProgression?: "ltr" | "rtl";
  toc?: TocConfig | boolean | string;
  tocTitle?: string;
  cover?: CoverConfig | string;
  timeout?: number;
  documentProcessor?: (
    option: import("@vivliostyle/vfm").StringifyMarkdownOptions,
    metadata: import("@vivliostyle/vfm").Metadata,
  ) => import("unified").Processor;
  documentMetadataReader?: (
    content: string,
  ) => import("@vivliostyle/vfm").Metadata;
  vfm?: VfmConfig;
  image?: string;
  http?: boolean;
  viewer?: string;
  viewerParam?: string;
  browser?: string;
  base?: string;
  server?: ServerConfig;
  static?: {
    [key: string]: string[] | string;
  };
  temporaryFilePrefix?: string;
  vite?: import("vite").UserConfig;
  viteConfigFile?: string | boolean;
};

ContentsEntryConfig

Properties

  • ContentsEntryConfig

    • rel: "contents"

    • path: string

    • output: string

    • title: string

    • theme: (ThemeConfig | string)[] | ThemeConfig | string

    • pageBreakBefore: "left" | "right" | "recto" | "verso"
      Specifies the page break position before this document. Useful for determining which side the first page of the document should be placed on in a two-page spread.

    • pageCounterReset: number
      Resets the starting page number of this document to the specified integer. Useful for controlling page numbers when including a page.

Type definition

type ContentsEntryConfig = {
  rel: "contents";
  path?: string;
  output?: string;
  title?: string;
  theme?:
    | (ThemeConfig | string)[]
    | ThemeConfig
    | string;
  pageBreakBefore?:
    | "left"
    | "right"
    | "recto"
    | "verso";
  pageCounterReset?: number;
};

ThemeConfig

Properties

  • ThemeConfig

    • specifier: string
      The specifier name for importing the theme package or the path to a CSS file.

      • An npm-style package argument is allowed (e.g., @vivliostyle/theme-academic@1, ./local-pkg).
      • A URL or a local path to a CSS file is allowed (e.g., ./style.css, https://example.com/style.css).

    • import: (string)[] | string
      The path(s) to the CSS file(s) to import from the package. Specify this if you want to import files other than the default.

Type definition

type ThemeConfig = {
  specifier: string;
  import?: string[] | string;
};

CoverEntryConfig

Properties

  • CoverEntryConfig

    • rel: "cover"

    • path: string

    • output: string

    • title: string

    • theme: (ThemeConfig | string)[] | ThemeConfig | string

    • imageSrc: string

    • imageAlt: string

    • pageBreakBefore: "left" | "right" | "recto" | "verso"
      Specifies the page break position before this document. Useful for determining which side the first page of the document should be placed on in a two-page spread.

Type definition

type CoverEntryConfig = {
  rel: "cover";
  path?: string;
  output?: string;
  title?: string;
  theme?:
    | (ThemeConfig | string)[]
    | ThemeConfig
    | string;
  imageSrc?: string;
  imageAlt?: string;
  pageBreakBefore?:
    | "left"
    | "right"
    | "recto"
    | "verso";
};

ArticleEntryConfig

Properties

  • ArticleEntryConfig

    • path: string

    • output: string

    • title: string

    • theme: (ThemeConfig | string)[] | ThemeConfig | string

    • encodingFormat: string

    • rel: (string)[] | string

    • documentProcessor: (option: import("@vivliostyle/vfm").StringifyMarkdownOptions, metadata: import("@vivliostyle/vfm").Metadata) => import("unified").Processor
      Custom function to provide a unified Processor for converting the source document to HTML.

    • documentMetadataReader: (content: string) => import("@vivliostyle/vfm").Metadata
      Custom function to extract metadata from the source document content.

Type definition

type ArticleEntryConfig = {
  path: string;
  output?: string;
  title?: string;
  theme?:
    | (ThemeConfig | string)[]
    | ThemeConfig
    | string;
  encodingFormat?: string;
  rel?: string[] | string;
  documentProcessor?: (
    option: import("@vivliostyle/vfm").StringifyMarkdownOptions,
    metadata: import("@vivliostyle/vfm").Metadata,
  ) => import("unified").Processor;
  documentMetadataReader?: (
    content: string,
  ) => import("@vivliostyle/vfm").Metadata;
};

OutputConfig

Properties

  • OutputConfig

    • path: string
      Specifies the output file name or directory. (default: <title>.pdf)

    • format: "pdf" | "epub" | "webpub"
      Specifies the output format.

    • renderMode: "local" | "docker"
      If set to docker, Vivliostyle will render the PDF using a Docker container. (default: local)

    • preflight Deprecated
      Use pdfPostprocess.preflight instead

    • preflightOption Deprecated
      Use pdfPostprocess.preflightOption instead

    • pdfPostprocess: PdfPostprocessConfig
      PDF post-processing options. When both pdfPostprocess and legacy options (pressReady, preflight, etc.) are specified, pdfPostprocess takes precedence.

Type definition

type OutputConfig = {
  path: string;
  format?: "pdf" | "epub" | "webpub";
  renderMode?: "local" | "docker";
  preflight?:
    | "press-ready"
    | "press-ready-local";
  preflightOption?: string[];
  pdfPostprocess?: PdfPostprocessConfig;
};

PdfPostprocessConfig

PDF post-processing options. When both pdfPostprocess and legacy options (pressReady, preflight, etc.) are specified, pdfPostprocess takes precedence.

Properties

  • PdfPostprocessConfig

    • preflight: "press-ready" | "press-ready-local"
      Apply the process to generate a print-ready PDF.

    • preflightOption: (string)[]
      Options for the preflight process (e.g., gray-scale, enforce-outline). Refer to the press-ready documentation for more information: press-ready

    • cmyk: boolean | CmykConfig
      Convert device-cmyk() colors to CMYK in the output PDF. Can be a boolean or a config object with overrideMap and warnUnmapped options.

    • replaceImage: (ReplaceImageEntry)[]
      Replace images in the output PDF. Each entry specifies a source image path and its replacement image path. Useful for replacing RGB images with CMYK versions.

Type definition

type PdfPostprocessConfig = {
  preflight?:
    | "press-ready"
    | "press-ready-local";
  preflightOption?: string[];
  cmyk?: boolean | CmykConfig;
  replaceImage?: ReplaceImageEntry[];
};

CmykConfig

Properties

  • CmykConfig

    • overrideMap: ("{tuple(Array)}")[]
      Custom RGB to CMYK color mapping. Each entry is a tuple of [{r, g, b}, {c, m, y, k}] where values are integers (0-10000).

    • warnUnmapped: boolean
      Warn when RGB colors not mapped to CMYK are encountered. (default: true)

    • mapOutput: string
      Output the CMYK color map to a JSON file at the specified path.

Type definition

type CmykConfig = {
  overrideMap?: "{tuple(Array)}"[];
  warnUnmapped?: boolean;
  mapOutput?: string;
};

ReplaceImageEntry

Properties

  • ReplaceImageEntry

    • source: string | RegExp
      Path to the source image file, or a RegExp pattern to match multiple files.

    • replacement: string
      Path to the replacement image file. When source is a RegExp, supports $1, $2, etc. for captured groups.

Type definition

type ReplaceImageEntry = {
  source: string | RegExp;
  replacement: string;
};

CopyAssetConfig

Properties

  • CopyAssetConfig

    • includes: (string)[]
      Directories and files to include as asset files. Supports wildcard characters for glob patterns.

    • excludes: (string)[]
      Directories and files to exclude from asset files. Supports wildcard characters for glob patterns.

    • includeFileExtensions: (string)[]
      File extensions to include as asset files. (default: [css, css.map, png, jpg, jpeg, svg, gif, webp, apng, ttf, otf, woff, woff2])

    • excludeFileExtensions: (string)[]
      File extensions to exclude from asset files.

Type definition

type CopyAssetConfig = {
  includes?: string[];
  excludes?: string[];
  includeFileExtensions?: string[];
  excludeFileExtensions?: string[];
};

TocConfig

Properties

  • TocConfig

    • title: string
      Title of the generated ToC document.

    • htmlPath: string
      Location where the generated ToC document will be saved. (default: index.html)

    • sectionDepth: number
      Depth of sections to include in the ToC document. (default: 0)

    • transformDocumentList: (nodeList: StructuredDocument[]) => (propsList: { children: any }[]) => any
      Function to transform the document list.

    • transformSectionList: (nodeList: StructuredDocumentSection[]) => (propsList: { children: any }[]) => any
      Function to transform the section list.

Type definition

type TocConfig = {
  title?: string;
  htmlPath?: string;
  sectionDepth?: number;
  transformDocumentList?: (
    nodeList: StructuredDocument[],
  ) => (
    propsList: { children: any }[],
  ) => any;
  transformSectionList?: (
    nodeList: StructuredDocumentSection[],
  ) => (
    propsList: { children: any }[],
  ) => any;
};

StructuredDocument

Properties

Type definition

type StructuredDocument = {
  title: string;
  href: string;
  children: StructuredDocument[];
  sections?: StructuredDocumentSection[];
};

StructuredDocumentSection

Properties

  • StructuredDocumentSection

Type definition

type StructuredDocumentSection = {
  headingHtml: string;
  headingText: string;
  level: number;
  children: StructuredDocumentSection[];
  href?: string;
  id?: string;
};

CoverConfig

Properties

  • CoverConfig

    • src: string
      Path to the cover image for the cover page.

    • name: string
      Alternative text for the cover image.

    • htmlPath: string | boolean
      Path where the generated cover document will be saved. (default: cover.html) If set to a falsy value, the cover document will not be generated.

Type definition

type CoverConfig = {
  src: string;
  name?: string;
  htmlPath?: string | boolean;
};

VfmConfig

Properties

  • VfmConfig

    • style: (string)[] | string
      Path(s) or URL(s) to custom stylesheets.

    • partial: boolean
      Output markdown fragments instead of a full document.

    • title: string
      Title of the document (ignored in partial mode).

    • language: string
      Language of the document (ignored in partial mode).

    • replace: (test: RegExp; match: (result: RegExpMatchArray, h: any) => Object string)[]
      Handlers for replacing matched HTML strings.

    • hardLineBreaks: boolean
      Insert <br> tags at hard line breaks without requiring spaces.

    • disableFormatHtml: boolean
      Disable automatic HTML formatting.

    • math: boolean
      Enable support for math syntax.

    • imgFigcaptionOrder: "img-figcaption" | "figcaption-img"
      Order of img and figcaption elements in figure.

    • assignIdToFigcaption: boolean
      Assign ID to figcaption instead of img/code.

Type definition

type VfmConfig = {
  style?: string[] | string;
  partial?: boolean;
  title?: string;
  language?: string;
  replace?: {
    test: RegExp;
    match: (
      result: RegExpMatchArray,
      h: any,
    ) => Object | string;
  }[];
  hardLineBreaks?: boolean;
  disableFormatHtml?: boolean;
  math?: boolean;
  imgFigcaptionOrder?:
    | "img-figcaption"
    | "figcaption-img";
  assignIdToFigcaption?: boolean;
};

ServerConfig

Properties

  • ServerConfig

    • host: boolean | string
      IP address the server should listen on. Set to true to listen on all addresses. (default: true if a PDF build with Docker render mode is required, otherwise false)

    • port: number
      Port the server should listen on. (default: 13000)

    • proxy: [key: (string)]: import("vite").ProxyOptions string
      Custom proxy rules for the Vivliostyle preview server.

    • allowedHosts: (string)[] | boolean
      The hostnames that are allowed to respond to. Set to true to allow all hostnames. See server.allowedHosts option of Vite for more details.

Type definition

type ServerConfig = {
  host?: boolean | string;
  port?: number;
  proxy?: {
    [key: string]:
      | import("vite").ProxyOptions
      | string;
  };
  allowedHosts?: string[] | boolean;
};