JavaScript API | Vivliostyle Documentation

JavaScript API

Exported members

Functions

build()

build(options): Promise<void>

Build publication file(s) from the given configuration.

import { build } from '@vivliostyle/cli';
build({
  configPath: './vivliostyle.config.js',
  logLevel: 'silent',
});

Parameters

options

author?

string = ...

bleed?

string = ...

browser?

string = ...

cmyk?

boolean | { mapOutput?: string; overrideMap?: [{ b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; } = CmykSchema

config?

string = ...

configData?

VivliostyleConfigSchema | null = ...

createConfigFileOnly?

boolean = ...

cropMarks?

boolean = ...

cropOffset?

string = ...

css?

string = ...

cwd?

string = ...

disableServerStartup?

boolean = ...

enableStaticServe?

boolean = ...

enableViewerStartPage?

boolean = ...

executableBrowser?

string = ...

host?

string | boolean = ...

ignoreHttpsErrors?

boolean = ...

image?

string = ...

input?

string = ...

language?

string = ...

logger?

LoggerInterface = ...

logLevel?

"info" | "silent" | "verbose" | "debug" = ...

openViewer?

boolean = ...

output?

string | object & object | (string | object & object)[] = ...

port?

number = ...

preflight?

"press-ready" | "press-ready-local" = ...

preflightOption?

string | string[] = ...

pressReady?

boolean = ...

projectPath?

string = ...

proxyBypass?

string = ...

proxyPass?

string = ...

proxyServer?

string = ...

proxyUser?

string = ...

quick?

boolean = ...

readingProgression?

"ltr" | "rtl" = ...

renderMode?

"local" | "docker" = ...

sandbox?

boolean = ...

signal?

AbortSignal = ...

singleDoc?

boolean = ...

size?

string = ...

stderr?

Writable = ...

stdin?

Readable = ...

stdout?

Writable = ...

style?

string = ...

template?

string = ...

theme?

string | object & object | (string | object & object)[] = ...

timeout?

number = ...

title?

string = ...

userStyle?

string = ...

viewer?

string = ...

viewerParam?

string = ...

vite?

UserConfig = ...

viteConfigFile?

string | boolean = ...

Returns

Promise<void>

create()

create(options): Promise<void>

Scaffold a new Vivliostyle project.

Parameters

options

author?

string = ...

bleed?

string = ...

browser?

string = ...

cmyk?

config?

string = ...

configData?

VivliostyleConfigSchema | null = ...

createConfigFileOnly?

boolean = ...

cropMarks?

boolean = ...

cropOffset?

string = ...

css?

string = ...

cwd?

string = ...

disableServerStartup?

boolean = ...

enableStaticServe?

boolean = ...

enableViewerStartPage?

boolean = ...

executableBrowser?

string = ...

host?

string | boolean = ...

ignoreHttpsErrors?

boolean = ...

image?

string = ...

input?

string = ...

language?

string = ...

logger?

LoggerInterface = ...

logLevel?

"info" | "silent" | "verbose" | "debug" = ...

openViewer?

boolean = ...

output?

string | object & object | (string | object & object)[] = ...

port?

number = ...

preflight?

"press-ready" | "press-ready-local" = ...

preflightOption?

string | string[] = ...

pressReady?

boolean = ...

projectPath?

string = ...

proxyBypass?

string = ...

proxyPass?

string = ...

proxyServer?

string = ...

proxyUser?

string = ...

quick?

boolean = ...

readingProgression?

"ltr" | "rtl" = ...

renderMode?

"local" | "docker" = ...

sandbox?

boolean = ...

signal?

AbortSignal = ...

singleDoc?

boolean = ...

size?

string = ...

stderr?

Writable = ...

stdin?

Readable = ...

stdout?

Writable = ...

style?

string = ...

template?

string = ...

theme?

string | object & object | (string | object & object)[] = ...

timeout?

number = ...

title?

string = ...

userStyle?

string = ...

viewer?

string = ...

viewerParam?

string = ...

vite?

UserConfig = ...

viteConfigFile?

string | boolean = ...

Returns

Promise<void>

createVitePlugin()

createVitePlugin(inlineConfig): Promise<Plugin<any>[]>

Parameters

inlineConfig

author?

string = ...

bleed?

string = ...

browser?

string = ...

cmyk?

config?

string = ...

configData?

VivliostyleConfigSchema | null = ...

createConfigFileOnly?

boolean = ...

cropMarks?

boolean = ...

cropOffset?

string = ...

css?

string = ...

cwd?

string = ...

disableServerStartup?

boolean = ...

enableStaticServe?

boolean = ...

enableViewerStartPage?

boolean = ...

executableBrowser?

string = ...

host?

string | boolean = ...

ignoreHttpsErrors?

boolean = ...

image?

string = ...

input?

string = ...

language?

string = ...

logger?

LoggerInterface = ...

logLevel?

"info" | "silent" | "verbose" | "debug" = ...

openViewer?

boolean = ...

output?

string | object & object | (string | object & object)[] = ...

port?

number = ...

preflight?

"press-ready" | "press-ready-local" = ...

preflightOption?

string | string[] = ...

pressReady?

boolean = ...

projectPath?

string = ...

proxyBypass?

string = ...

proxyPass?

string = ...

proxyServer?

string = ...

proxyUser?

string = ...

quick?

boolean = ...

readingProgression?

"ltr" | "rtl" = ...

renderMode?

"local" | "docker" = ...

sandbox?

boolean = ...

signal?

AbortSignal = ...

singleDoc?

boolean = ...

size?

string = ...

stderr?

Writable = ...

stdin?

Readable = ...

stdout?

Writable = ...

style?

string = ...

template?

string = ...

theme?

string | object & object | (string | object & object)[] = ...

timeout?

number = ...

title?

string = ...

userStyle?

string = ...

viewer?

string = ...

viewerParam?

string = ...

vite?

UserConfig = ...

viteConfigFile?

string | boolean = ...

Returns

Promise<Plugin<any>[]>

defineConfig()

defineConfig(config): VivliostyleConfigSchema

Define the configuration for Vivliostyle CLI.

Parameters

config

VivliostyleConfigSchema

Returns

VivliostyleConfigSchema

preview()

preview(options): Promise<ViteDevServer>

Open a browser for previewing the publication.

Parameters

options

author?

string = ...

bleed?

string = ...

browser?

string = ...

cmyk?

config?

string = ...

configData?

VivliostyleConfigSchema | null = ...

createConfigFileOnly?

boolean = ...

cropMarks?

boolean = ...

cropOffset?

string = ...

css?

string = ...

cwd?

string = ...

disableServerStartup?

boolean = ...

enableStaticServe?

boolean = ...

enableViewerStartPage?

boolean = ...

executableBrowser?

string = ...

host?

string | boolean = ...

ignoreHttpsErrors?

boolean = ...

image?

string = ...

input?

string = ...

language?

string = ...

logger?

LoggerInterface = ...

logLevel?

"info" | "silent" | "verbose" | "debug" = ...

openViewer?

boolean = ...

output?

string | object & object | (string | object & object)[] = ...

port?

number = ...

preflight?

"press-ready" | "press-ready-local" = ...

preflightOption?

string | string[] = ...

pressReady?

boolean = ...

projectPath?

string = ...

proxyBypass?

string = ...

proxyPass?

string = ...

proxyServer?

string = ...

proxyUser?

string = ...

quick?

boolean = ...

readingProgression?

"ltr" | "rtl" = ...

renderMode?

"local" | "docker" = ...

sandbox?

boolean = ...

signal?

AbortSignal = ...

singleDoc?

boolean = ...

size?

string = ...

stderr?

Writable = ...

stdin?

Readable = ...

stdout?

Writable = ...

style?

string = ...

template?

string = ...

theme?

string | object & object | (string | object & object)[] = ...

timeout?

number = ...

title?

string = ...

userStyle?

string = ...

viewer?

string = ...

viewerParam?

string = ...

vite?

UserConfig = ...

viteConfigFile?

string | boolean = ...

Returns

Promise<ViteDevServer>

VFM()

VFM(options?, metadata?): Processor

Create Unified processor for Markdown AST and Hypertext AST.

Parameters

options?

StringifyMarkdownOptions

Options.

metadata?

Metadata

Returns

Processor

Unified processor.

Interfaces

StringifyMarkdownOptions

Option for convert Markdown to a stringify (HTML).

Properties

Property	Type	Description
`assignIdToFigcaption?`	`boolean`	Assign ID to figcaption instead of img/code.
`disableFormatHtml?`	`boolean`	Disable automatic HTML format.
`hardLineBreaks?`	`boolean`	Add `<br>` at the position of hard line breaks, without needing spaces.
`imgFigcaptionOrder?`	`"img-figcaption"` \| `"figcaption-img"`	Order of img and figcaption elements in figure.
`language?`	`string`	Document language (ignored in partial mode).
`math?`	`boolean`	Enable math syntax.
`partial?`	`boolean`	Output markdown fragments.
`replace?`	`ReplaceRule`[]	Replacement handler for HTML string.
`style?`	`string` \| `string`[]	Custom stylesheet path/URL.
`title?`	`string`	Document title (ignored in partial mode).

TemplateVariable

Extends

Omit<ParsedVivliostyleInlineConfig, "theme">

Properties

Property	Type
`author`	`string`
`bleed?`	`string`
`browser?`	`object`
`browser.tag?`	`string`
`browser.type`	`"chrome"` \| `"chromium"` \| `"firefox"`
`cliVersion`	`string`
`cmyk?`	`boolean` \| { `mapOutput?`: `string`; `overrideMap?`: [{ `b`: `number`; `g`: `number`; `r`: `number`; }, { `c`: `number`; `k`: `number`; `m`: `number`; `y`: `number`; }][]; `warnUnmapped?`: `boolean`; }
`config?`	`string`
`configData?`	`VivliostyleConfigSchema` \| `null`
`coreVersion`	`string`
`createConfigFileOnly?`	`boolean`
`cropMarks?`	`boolean`
`cropOffset?`	`string`
`css?`	`string`
`cwd?`	`string`
`disableServerStartup?`	`boolean`
`enableStaticServe?`	`boolean`
`enableViewerStartPage?`	`boolean`
`executableBrowser?`	`string`
`host?`	`string` \| `boolean`
`ignoreHttpsErrors?`	`boolean`
`image?`	`string`
`input?`	`object`
`input.entry`	`string`
`input.format`	`InputFormat`
`language`	`string`
`logger?`	`LoggerInterface`
`logLevel?`	`"info"` \| `"silent"` \| `"verbose"` \| `"debug"`
`openViewer?`	`boolean`
`output?`	`object` & `object` & `object`[]
`port?`	`number`
`preflight?`	`"press-ready"` \| `"press-ready-local"`
`preflightOption?`	`string`[]
`pressReady?`	`boolean`
`projectPath`	`string`
`proxyBypass?`	`string`
`proxyPass?`	`string`
`proxyServer?`	`string`
`proxyUser?`	`string`
`quick?`	`boolean`
`readingProgression?`	`"ltr"` \| `"rtl"`
`renderMode?`	`"local"` \| `"docker"`
`sandbox?`	`boolean`
`signal?`	`AbortSignal`
`singleDoc?`	`boolean`
`size?`	`string`
`stderr?`	`Writable`
`stdin?`	`Readable`
`stdout?`	`Writable`
`style?`	`string`
`template?`	`string`
`theme?`	`string` \| `object` & `object` \| (`string` \| `object` & `object`)[]
`themePackage?`	`VivliostylePackageJson`
`timeout?`	`number`
`title`	`string`
`userStyle?`	`string`
`viewer?`	`string`
`viewerParam?`	`string`
`vite?`	`UserConfig`
`viteConfigFile?`	`string` \| `boolean`

Type Aliases

Metadata

Metadata = object

Metadata from Frontmatter.

Properties

base?

optional base: Attribute[]

Attributes of <base>.

body?

optional body: Attribute[]

Attributes of <body>.

class?

optional class: string

Value of <html class="...">.

custom?

optional custom: object

A set of key-value pairs that are specified in readMetadata not to be processed as <meta>. The data types converted from Frontmatter's YAML are retained. Use this if want to add custom metadata with a third party tool.

Index Signature

[key: string]: any

dir?

optional dir: string

Value of <html dir="...">. e.g. ltr, rtl, auto.

head?

optional head: string

<head>...</head>, reserved for future use.

html?

optional html: Attribute[]

Attributes of <html>. The id, lang, dir, and class specified in the root take precedence over the value of this property.

id?

optional id: string

Value of <html id="...">.

lang?

optional lang: string

Value of <html lang="...">.

link?

optional link: Attribute[][]

Attribute collection of <link>.

meta?

optional meta: Attribute[][]

Attribute collection of <meta>.

script?

optional script: Attribute[][]

Attribute collection of <script>.

style?

optional style: string

<style>...</style>, reserved for future use.

title?

optional title: string

Value of <title>...</title>.

vfm?

optional vfm: VFMSettings

VFM settings.

StructuredDocument

StructuredDocument = object

See

https://github.com/vivliostyle/vivliostyle-cli/blob/main/docs/config.md

Properties

children

children: StructuredDocument[]

href

href: string

sections?

optional sections: StructuredDocumentSection[]

title

title: string

StructuredDocumentSection

StructuredDocumentSection = object

See

https://github.com/vivliostyle/vivliostyle-cli/blob/main/docs/config.md

Properties

children

children: StructuredDocumentSection[]

headingHtml

headingHtml: string

headingText

headingText: string

href?

optional href: string

id?

optional id: string

level

level: number

VivliostyleConfigSchema

VivliostyleConfigSchema = BuildTask[] | BuildTask

See

https://github.com/vivliostyle/vivliostyle-cli/blob/main/docs/config.md

VivliostylePackageMetadata

VivliostylePackageMetadata = SchemaWithPipe<readonly [Omit<ObjectSchema<{ template: SchemaWithPipe<readonly [RecordSchema<SchemaWithPipe<readonly [..., ..., ...]>, ObjectSchema<{ description: ...; name: ...; prompt: ...; source: ...; }, undefined>, undefined>, TitleAction<{[key: string]: object; }, "VivliostyleTemplateMetadata">]>; theme: SchemaWithPipe<readonly [ObjectSchema<{ author: SchemaWithPipe<...>; category: SchemaWithPipe<...>; name: SchemaWithPipe<...>; style: SchemaWithPipe<...>; topics: SchemaWithPipe<...>; }, undefined>, TitleAction<{ author?: ... | ...; category?: ... | ...; name?: ... | ...; style?: ... | ...; topics?: ... | ...; }, "VivliostyleThemeMetadata">]>; }, undefined>, "entries" | "~types" | "~run" | "~standard"> & object, TitleAction<{ template?: {[key: string]: object; }; theme?: { author?: string; category?: string; name?: string; style?: string; topics?: string[]; }; }, "VivliostylePackageMetadata">]>

VivliostylePackageMetadata

VivliostylePackageMetadata = v.InferInput<typeof VivliostylePackageMetadata>

Variables

readMetadata()

const readMetadata: (md, customKeys?) => Metadata

Read metadata from Markdown frontmatter.

Keys that are not defined as VFM are treated as meta. If you specify a key name in customKeys, the key and its data type will be preserved and stored in custom instead of meta.

Parameters

md

string

Markdown.

customKeys?

string[]

A collection of key names to be ignored by meta processing.

Returns

Metadata

Metadata.