Config Reference

Type definition

type VivliostyleConfigSchema =
  | 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).

  • css: CssConfig
    Options for CSS processing.

  • 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;
  css?: CssConfig;
  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;
};

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;
};

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;
};

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";
};

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;
};

Properties

• OutputConfig

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

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

  • renderMode Deprecated
    If set to docker, Vivliostyle will render the PDF using a Docker container. (default: local) renderMode: docker is deprecated and may be removed in a future major release. See https://github.com/vivliostyle/vivliostyle-cli/issues/823

  • 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;
};

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 options such as reserveMap, fallback, ifUnmappedColorsFound, and ifIncompatibleImagesFound.

  • replaceImage: (ReplaceImageEntry | ReplaceFunction | ImageConversionReplacement)[]
    Replace images in the output PDF. Each entry specifies source and replacement paths, combines a source path with a replacement function or color conversion, or applies one to every replaceable image.

Type definition

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

Properties

• CmykConfig

  • overrideMap Deprecated
    Use fallback instead. Each entry is a tuple of [rgb, {c, m, y, k}] that overrides the color mapping. RGB can be an object {r, g, b} with integers (0-10000) or a hex color string (e.g. "#ff0000").

  • fallback: import("@vivliostyle/cli").CmykConvertFunction | CmykConversion
    Conversion applied to RGB colors not covered by the regular mapping. Accepts a custom function or a color conversion created by a fallback factory. RGB and CMYK channel values are integers on a 0-10000 scale. Return null from a custom function to leave the color unmapped. Exceptions and invalid return values fail the build.

  • reserveMap: ("{tuple(Array)}")[]
    Pre-register RGB to CMYK color mappings for use in SVG or other non-CSS contexts. Each entry is a tuple of [rgb, {c, m, y, k}]. RGB can be an object {r, g, b} with integers (0-10000) or a hex color string (e.g. "#ff0000").

  • warnUnmapped Deprecated
    Use ifUnmappedColorsFound instead. true corresponds to "warn" and false to "ignore". When both are specified, ifUnmappedColorsFound takes precedence.

  • ifUnmappedColorsFound: "warn" | "error" | "ignore"
    What to do when RGB colors not mapped to CMYK are encountered: log a warning, fail the build, or do nothing. (default: warn)

  • ifIncompatibleImagesFound: "warn" | "error" | "ignore"
    What to do when the replaceImage scan encounters images whose color spaces are not DeviceCMYK or DeviceGray: log a warning, fail the build, or do nothing. (default: warn)

  • mapOutput: string
    Output the CMYK color map to a JSON file at the specified path. Colors converted by the fallback function are not included.

Type definition

type CmykConfig = {
  overrideMap?: "{tuple(Array)}"[];
  fallback?:
    | import("@vivliostyle/cli").CmykConvertFunction
    | CmykConversion;
  reserveMap?: "{tuple(Array)}"[];
  warnUnmapped?: boolean;
  ifUnmappedColorsFound?:
    | "warn"
    | "error"
    | "ignore";
  ifIncompatibleImagesFound?:
    | "warn"
    | "error"
    | "ignore";
  mapOutput?: string;
};

Type definition

type CmykConversion =
  | {
      kind: "builtin";
      destination:
        | "DeviceGray"
        | "DeviceCMYK";
      inputProfile?: string;
    }
  | {
      kind: "icc";
      inputProfile?: string;
      outputProfile: string;
    };

Properties

• ReplaceImageEntry

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

  • replacement: string | ReplaceFunction | ImageConversionReplacement
    Path to the replacement image file, a replacement function or color conversion, or when source is a RegExp with a string replacement, a pattern supporting $1, $2, etc. for captured groups.

Type definition

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

Type definition

type ReplaceFunction =
  import("@vivliostyle/cli").ReplaceFunction;

Type definition

type ImageConversionReplacement =
  | {
      kind: "builtin";
      destination:
        | "DeviceGray"
        | "DeviceRGB"
        | "DeviceCMYK";
      inputProfile?: string;
      source?: never;
      replacement?: never;
    }
  | {
      kind: "icc";
      inputProfile?: string;
      outputProfile: string;
      source?: never;
      replacement?: never;
    };

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[];
};

Properties

• TocConfig

  • title: string
    Title used for the generated ToC heading and publication manifest entry.

  • compose: ({ h }: { h: typeof import("hastscript").h }) => ({ heading, content }: { heading: import("hast").Element & { tagName: "h2"; children: [import("hast").Text] }; content: import("hast").Element }) => import("hast").ElementContent[]
    Function to compose the contents of the ToC navigation element.

  • 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;
  compose?: ({
    h,
  }: {
    h: typeof import("hastscript").h;
  }) => ({
    heading,
    content,
  }: {
    heading: import("hast").Element & {
      tagName: "h2";
      children: [import("hast").Text];
    };
    content: import("hast").Element;
  }) => import("hast").ElementContent[];
  htmlPath?: string;
  sectionDepth?: number;
  transformDocumentList?: (
    nodeList: StructuredDocument[],
  ) => (
    propsList: { children: any }[],
  ) => any;
  transformSectionList?: (
    nodeList: StructuredDocumentSection[],
  ) => (
    propsList: { children: any }[],
  ) => any;
};

Properties

• StructuredDocument

  • title: string

  • href: string

  • children: (StructuredDocument)[]

  • sections: (StructuredDocumentSection)[]

Type definition

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

Properties

• StructuredDocumentSection

  • headingHtml: string

  • headingText: string

  • level: number

  • children: (StructuredDocumentSection)[]

  • href: string

  • id: string

Type definition

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

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;
};

Properties

• VfmConfig

  • style: string | (string)[]
    Custom stylesheet path/URL.

  • title: string
    Document title (ignored in partial mode).

  • language: string
    Document language (ignored in partial mode).

  • editPlugins: (plugins: BuiltinPlugins) => EditedPlugins
    Edit the plugin lists assembled by VFM before they are used. Only head-prepend and tail-append to the built-in lists are behaviorally stable across minor releases.

  • hardLineBreaks: boolean
    Add <br> at the position of hard line breaks, without needing spaces.

  • math: boolean
    Enable math syntax.

  • mathRenderer: "mathjax" | "mathml"
    Renderer used when math is enabled. 'mathjax' (default): keep the LaTeX source and load MathJax for runtime rendering. 'mathml': convert LaTeX to MathML at build time via temml, with no runtime script.

  • partial: boolean
    Output markdown fragments.

  • disableFormatHtml: boolean
    Disable automatic HTML format.

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

  • assignIdToFigcaption: boolean
    Assign ID to figcaption instead of the <code> element.

  • captionlessImagePolicy: "paragraph" | "figure" | "figure-with-figcaption"
    How to render an image-only paragraph whose alt is empty.

  • parseFigcaptionAsInline: boolean
    Re-parse figcaption text as inline markdown (math, ruby, emphasis, footnotes, etc.).

  • footnote: "pandoc" | "dpub" | "gcpm" | mode: "pandoc"} {mode: "dpub"; call?: import("hast").Properties | DpubCallFactory; body?: import("hast").Properties | DpubBodyFactory | mode: "gcpm"; body?: import("hast").Properties GcpmBodyFactory; duplicatedCall?: import("hast").Properties | GcpmDuplicatedCallFactory

  • rewriteRelativeHrefExtensions: boolean | (string)[]
    Rewrite the trailing extension of relative hyperlink hrefs to .html. true is shorthand for ["md"]; pass an array (e.g. ["md", "adoc"]) to broaden the set of source extensions whose links get rewritten. Only <a> and <area> elements are touched (the elements that unconditionally create hyperlinks per HTML Standard §4.6); <base> and <link> are left alone because their href is not an author-specified navigation target. Only relative references (no scheme, no host, and the path does not start with /) are touched; remote URLs and rooted paths are left untouched. The rewrite is purely syntactic. The file system is not consulted, so producing the target `.html` is the embedder's responsibility.

  • table: cell?: "align-attribute" "align-class" | "align-style" | TableCellHook

  • replace: (test: RegExp; match: (result: RegExpMatchArray, h: typeof import("hastscript").h) => import("unist").Node string)[]

Type definition

type VfmConfig = {
  style?: string | string[];
  title?: string;
  language?: string;
  editPlugins?: (
    plugins: BuiltinPlugins,
  ) => EditedPlugins;
  hardLineBreaks?: boolean;
  math?: boolean;
  mathRenderer?: "mathjax" | "mathml";
  partial?: boolean;
  disableFormatHtml?: boolean;
  imgFigcaptionOrder?:
    | "img-figcaption"
    | "figcaption-img";
  assignIdToFigcaption?: boolean;
  captionlessImagePolicy?:
    | "paragraph"
    | "figure"
    | "figure-with-figcaption";
  parseFigcaptionAsInline?: boolean;
  footnote?:
    | "pandoc"
    | "dpub"
    | "gcpm"
    | { mode: "pandoc" }
    | {
        mode: "dpub";
        call?:
          | import("hast").Properties
          | DpubCallFactory;
        body?:
          | import("hast").Properties
          | DpubBodyFactory;
      }
    | {
        mode: "gcpm";
        body?:
          | import("hast").Properties
          | GcpmBodyFactory;
        duplicatedCall?:
          | import("hast").Properties
          | GcpmDuplicatedCallFactory;
      };
  rewriteRelativeHrefExtensions?:
    | boolean
    | string[];
  table?: {
    cell?:
      | "align-attribute"
      | "align-class"
      | "align-style"
      | TableCellHook;
  };
  replace?: {
    test: RegExp;
    match: (
      result: RegExpMatchArray,
      h: typeof import("hastscript").h,
    ) => import("unist").Node | string;
  }[];
};

Properties

• CssConfig

  • postcss: string | import("postcss").ProcessOptions & { plugins?: import("postcss").AcceptedPlugin[] }
    Inline PostCSS config, or a directory to search for the PostCSS config file from. (default: the directory of the Vivliostyle config file) If an inline config is provided, the PostCSS config file is not searched.

Type definition

type CssConfig = {
  postcss?:
    | string
    | (import("postcss").ProcessOptions & {
        plugins?: import("postcss").AcceptedPlugin[];
      });
};

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;
};