api-javascript.md

JavaScript API

Exported members

Functions

• build
• builtinCmykConversion
• builtinCmykReplacement
• builtinGrayConversion
• builtinGrayReplacement
• create
• createVitePlugin
• defineConfig
• preview
• VFM

Interfaces

• ColorConversionOptions
• ImageContext
• StringifyMarkdownOptions
• TemplateVariable

Type Aliases

• CmykConvertFunction
• Metadata
• ReplaceFunction
• StructuredDocument
• StructuredDocumentSection
• VivliostyleConfigSchema
• VivliostylePackageMetadata
• VivliostylePackageMetadata

Variables

• readMetadata

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?: ([string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }] | (rgb) => { c: number; k: number; m: number; y: number; } | Promise<{ c: number; k: number; m: number; y: number; }>)[]; reserveMap?: [string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; warnUnreplacedImages?: 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 = ...

installDependencies?

boolean = ...

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 | false | object & object | (string | object & object)[] = ...

timeout?

number = ...

title?

string = ...

userStyle?

string = ...

viewer?

string = ...

viewerParam?

string = ...

vite?

UserConfig = ...

viteConfigFile?

string | boolean = ...

Returns

Promise<void>

---

builtinCmykConversion()

builtinCmykConversion(options): CmykConvertFunction

Returns a CmykConvertFunction that converts RGB colors to CMYK. Internally creates a 1x1 RGB pixmap and delegates to builtinCmykReplacement for the actual conversion, reusing ICC profile support.

Parameters

options

ColorConversionOptions = {}

Returns

CmykConvertFunction

---

builtinCmykReplacement()

builtinCmykReplacement(options): ReplaceFunction

Returns a ReplaceFunction that converts RGB images to CMYK. When called without arguments, uses mupdf's DeviceCMYK color space. An output ICC profile can be provided for profile-based conversion.

Parameters

options

ColorConversionOptions = {}

Returns

ReplaceFunction

---

builtinGrayConversion()

builtinGrayConversion(options): CmykConvertFunction

Returns a CmykConvertFunction that converts RGB colors to grayscale (K only). Internally delegates to builtinGrayReplacement and maps the Gray value to K.

Parameters

options

ColorConversionOptions = {}

Returns

CmykConvertFunction

---

builtinGrayReplacement()

builtinGrayReplacement(options): ReplaceFunction

Returns a ReplaceFunction that converts RGB images to grayscale. When called without arguments, uses mupdf's DeviceGray color space. An output ICC profile can be provided for profile-based conversion.

Parameters

options

ColorConversionOptions = {}

Returns

ReplaceFunction

---

create()

create(options): Promise<void>

Scaffold a new Vivliostyle project.

Parameters

options

author?

string = ...

bleed?

string = ...

browser?

string = ...

cmyk?

boolean | { mapOutput?: string; overrideMap?: ([string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }] | (rgb) => { c: number; k: number; m: number; y: number; } | Promise<{ c: number; k: number; m: number; y: number; }>)[]; reserveMap?: [string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; warnUnreplacedImages?: 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 = ...

installDependencies?

boolean = ...

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 | false | 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?

boolean | { mapOutput?: string; overrideMap?: ([string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }] | (rgb) => { c: number; k: number; m: number; y: number; } | Promise<{ c: number; k: number; m: number; y: number; }>)[]; reserveMap?: [string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; warnUnreplacedImages?: 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 = ...

installDependencies?

boolean = ...

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 | false | 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?

boolean | { mapOutput?: string; overrideMap?: ([string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }] | (rgb) => { c: number; k: number; m: number; y: number; } | Promise<{ c: number; k: number; m: number; y: number; }>)[]; reserveMap?: [string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; warnUnreplacedImages?: 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 = ...

installDependencies?

boolean = ...

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 | false | 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

ColorConversionOptions

Properties

Property	Type
outputProfile?	Uint8Array<ArrayBufferLike>

---

ImageContext

Methods

asPNG()

asPNG(): Uint8Array

Returns

Uint8Array

---

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?: ([string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }] | (rgb) => { c: number; k: number; m: number; y: number; } | Promise<{ c: number; k: number; m: number; y: number; }>)[]; reserveMap?: [string | { b: number; g: number; r: number; }, { c: number; k: number; m: number; y: number; }][]; warnUnmapped?: boolean; warnUnreplacedImages?: 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
installDependencies?	boolean
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

CmykConvertFunction()

CmykConvertFunction = (rgb) => CMYKValue | Promise<CMYKValue>

Parameters

rgb

RGBValue

Returns

CMYKValue | Promise<CMYKValue>

---

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.

---

ReplaceFunction()

ReplaceFunction = (image) => Uint8Array | Promise<Uint8Array>

Parameters

image

ImageContext

Returns

Uint8Array | Promise<Uint8Array>

---

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.